refactor(docs): Refactor the development section (#2438)

33 files changed, 114 insertions, 76 deletions

diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md
index 73087fb81c..4d119ade96 100644
--- a/docs/blog/2021-07-17-zephyr-2-5.md
+++ b/docs/blog/2021-07-17-zephyr-2-5.md
@@ -60,7 +60,7 @@ Once the container has rebuilt, VS Code will be running the 2.5 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 2.5:
 
-- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/local-toolchain/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - run `west update` to pull the updated Zephyr version and its dependencies
 
diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md
index 193256a70f..15a79500f6 100644
--- a/docs/blog/2022-04-02-zephyr-3-0.md
+++ b/docs/blog/2022-04-02-zephyr-3-0.md
@@ -61,7 +61,7 @@ Once the container has rebuilt, VS Code will be running the 3.0 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 3.0:
 
-- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/local-toolchain/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - run `west update` to pull the updated Zephyr version and its dependencies
 
diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md
index f0f54a96d9..55faeb41c2 100644
--- a/docs/blog/2022-04-10-zmk-sotf-5.md
+++ b/docs/blog/2022-04-10-zmk-sotf-5.md
@@ -219,7 +219,7 @@ This can be useful to be sure that lowering brightness doesn't set the brightnes
 
 ## Board/Shield Metadata
 
-[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our
+[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our
 more nuanced GH Actions automation for testing changes to ZMK.
 
 ## Coming Soon!
diff --git a/docs/blog/2023-04-06-zephyr-3-2.md b/docs/blog/2023-04-06-zephyr-3-2.md
index 21d3816d90..a7d7240232 100644
--- a/docs/blog/2023-04-06-zephyr-3-2.md
+++ b/docs/blog/2023-04-06-zephyr-3-2.md
@@ -86,7 +86,7 @@ Once the container has rebuilt, VS Code will be running the 3.2 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 3.2:
 
-- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/local-toolchain/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - Install the latest version of `west` by running `pip3 install --user --update west`.
 - pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - run `west update` to pull the updated Zephyr version and its dependencies
diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md
index 441c023335..609425ee13 100644
--- a/docs/blog/2023-10-05-zmk-sotf-6.md
+++ b/docs/blog/2023-10-05-zmk-sotf-6.md
@@ -173,7 +173,7 @@ For users or future contributors that might want to dive into writing their own
 
 #### Shield interconnects
 
-[petejohanson] updated the [new shield guide](/docs/development/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607).
+[petejohanson] updated the [new shield guide](/docs/development/hardware-integration/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607).
 
 #### Bluetooth feature page
 
diff --git a/docs/blog/2024-02-09-zephyr-3-5.md b/docs/blog/2024-02-09-zephyr-3-5.md
index 8b3c941acd..2362829e9f 100644
--- a/docs/blog/2024-02-09-zephyr-3-5.md
+++ b/docs/blog/2024-02-09-zephyr-3-5.md
@@ -69,7 +69,7 @@ Once the container has rebuilt, VS Code will be running the 3.5 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 3.5:
 
-- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/local-toolchain/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - Install the latest version of `west` by running `pip3 install --user --update west`.
 - Pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - Run `west update` to pull the updated Zephyr version and its dependencies
diff --git a/docs/docs/config/index.md b/docs/docs/config/index.md
index 409b1f04ed..354633a128 100644
--- a/docs/docs/config/index.md
+++ b/docs/docs/config/index.md
@@ -64,7 +64,7 @@ ZMK will search the shield folder for the following config files _in addition_ t
 
 Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders.
 
-For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/new-shield.mdx) guide.
+For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/hardware-integration/new-shield.mdx) guide.
 
 ## Kconfig Files
 
diff --git a/docs/docs/config/kscan.md b/docs/docs/config/kscan.md
index af4a63fe2a..b8a3660bd9 100644
--- a/docs/docs/config/kscan.md
+++ b/docs/docs/config/kscan.md
@@ -344,7 +344,7 @@ Transforms should be used any time the physical layout of a keyboard's keys does
 
 Transforms can also be used for keyboards with multiple layouts. You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps.
 
-See the [new shield guide](../development/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform.
+See the [new shield guide](../development/hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform.
 
 ### Devicetree
 
diff --git a/docs/docs/customization.md b/docs/docs/customization.md
index 638ddbfc74..e35bb42671 100644
--- a/docs/docs/customization.md
+++ b/docs/docs/customization.md
@@ -40,9 +40,9 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
 :::
 
 :::note
-It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup/index.md) and
-[building instructions](development/build-flash.mdx), which includes pointers to
-[building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder).
+It is also possible to build firmware locally on your computer by following the [toolchain setup](development/local-toolchain/setup/index.md) and
+[building instructions](development/local-toolchain/build-flash.mdx), which includes pointers to
+[building using your `zmk-config` folder](development/local-toolchain/build-flash.mdx#building-from-zmk-config-folder).
 :::
 
 ## Flashing Your Changes
diff --git a/docs/docs/development/clean-room.md b/docs/docs/development/contributing/clean-room.md
index 45fa324e6b..45fa324e6b 100644
--- a/docs/docs/development/clean-room.md
+++ b/docs/docs/development/contributing/clean-room.md
diff --git a/docs/docs/development/documentation.md b/docs/docs/development/contributing/documentation.md
index 169642ba71..5bca630311 100644
--- a/docs/docs/development/documentation.md
+++ b/docs/docs/development/contributing/documentation.md
@@ -3,6 +3,10 @@ title: Documentation
 sidebar_label: Documentation
 ---
 
+:::danger
+Before reading this section, it is **vital** that you read through our [clean room policy](clean-room.md).
+:::
+
 This document outlines how to test your documentation changes locally and prepare the changes for a pull request.
 
 The documentation is written with [Docusaurus](https://docusaurus.io/). The ZMK source code has all of the necessary Docusaurus dependencies included, but referencing their documentation can be helpful at times.
diff --git a/docs/docs/development/boards-shields-keymaps.md b/docs/docs/development/hardware-integration/boards-shields-keymaps.md
index e936f992b0..c6e141b9aa 100644
--- a/docs/docs/development/boards-shields-keymaps.md
+++ b/docs/docs/development/hardware-integration/boards-shields-keymaps.md
@@ -11,7 +11,7 @@ The foundational elements needed to get a specific keyboard working with ZMK can
 - A keymap, which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers.
 
 These three core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that
-keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](../faq.md#why-boards-and-shields-why-not-just-keyboard).
+keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](../../faq.md#why-boards-and-shields-why-not-just-keyboard).
 
 ## Self-Contained Keyboard
 
@@ -34,7 +34,7 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck
 
 ## Pro Micro Compatible Keyboard
 
-![Labelled Pro Micro pins](../assets/interconnects/pro_micro/pinout.png)
+![Labelled Pro Micro pins](../../assets/interconnects/pro_micro/pinout.png)
 
 For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places
 in the _shield_ definition for that keyboard, allowing users to
diff --git a/docs/docs/development/hardware-metadata-files.md b/docs/docs/development/hardware-integration/hardware-metadata-files.md
index 46fad411ab..46fad411ab 100644
--- a/docs/docs/development/hardware-metadata-files.md
+++ b/docs/docs/development/hardware-integration/hardware-metadata-files.md
diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx
index 2ea23150cf..6d5921611e 100644
--- a/docs/docs/development/new-shield.mdx
+++ b/docs/docs/development/hardware-integration/new-shield.mdx
@@ -4,11 +4,15 @@ title: New Keyboard Shield
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
-import KeymapExampleFile from "../keymap-example-file.md";
+import KeymapExampleFile from "../../keymap-example-file.md";
 
 import InterconnectTabs from "@site/src/components/interconnect-tabs";
 import Metadata from "@site/src/data/hardware-metadata.json";
 
+:::danger
+Before reading this section, it is **vital** that you read through our [clean room policy](../contributing/clean-room.md).
+:::
+
 ## Overview
 
 This guide will walk through the steps necessary to add ZMK support for a keyboard that uses an add-on MCU board (e.g. Pro Micro compatible) to provide the microprocessor.
@@ -29,7 +33,7 @@ The high level steps are:
 It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
 
 :::note
-ZMK support for [split keyboards](../features/split-keyboards.md) requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place.
+ZMK support for [split keyboards](../../features/split-keyboards.md) requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place.
 :::
 
 ## New Zephyr Module Repository
@@ -60,13 +64,6 @@ Neither of these should be moved out of their parent directory. The other files
 
 ## New Shield Directory
 
-:::note
-This guide describes how to add a shield to an independently managed Zephyr module repository. This is the
-preferred way to handle boards and shields moving forward in ZMK, although the tooling to make this easier
-for users is still improving. ZMK does have a collection of boards/shields in the ZMK main repository, which are planned to be phased out, but until that is complete, there _may_ be a few select scenarios where adding your keyboard to ZMK itself is preferred. Due the volume of PRs and the focus of ZMK development not being merging of keyboard PRs, you are highly encouraged to use an out-of-tree Zephyr module repository to manage your definitions. Should you choose to try to get your keyboard included in ZMK main repository, the paths in the rest of the guide would be nested under the `app/` folder there instead. For example, `boards/shields/<keyboard_name>` should now be
-`app/boards/shields/<keyboard_name>`.
-:::
-
 Shields in Zephyr module "board root" go into the `boards/shields/` directory; that means the new shield directory in your module repository should be:
 
 ```bash
@@ -76,7 +73,7 @@ mkdir boards/shields/<keyboard_name>
 ## Base Kconfig Files
 
 :::tip[Example shields]
-You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../hardware.mdx) in order to copy and modify as a starting point.
+You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../../hardware.mdx) in order to copy and modify as a starting point.
 :::
 
 There are two required Kconfig files that need to be created for your new keyboard
@@ -95,7 +92,7 @@ config SHIELD_MY_BOARD
 Kconfig uses only commas for delimiters, and keeps all whitespaces in the function call. Therefore do not add a whitespace after the comma when configuring your shield as this would be treated as <code>&nbsp;my_board</code> (with a leading whitespace) and will cause issues.
 :::
 
-This will make sure that a new configuration value named `SHIELD_MY_BOARD` is set to true whenever `my_board` is used as the shield name, either as the `SHIELD` variable [in a local build](build-flash.mdx) or in your `build.yaml` file [when using Github Actions](../customization). Note that this configuration value will be used in `Kconfig.defconfig` to set other properties about your shield, so make sure that they match.
+This will make sure that a new configuration value named `SHIELD_MY_BOARD` is set to true whenever `my_board` is used as the shield name, either as the `SHIELD` variable [in a local build](../local-toolchain/build-flash.mdx) or in your `build.yaml` file [when using Github Actions](../../customization.md). Note that this configuration value will be used in `Kconfig.defconfig` to set other properties about your shield, so make sure that they match.
 
 **For split boards**, you will need to add configurations for the left and right sides. For example, if your split halves are named `my_board_left` and `my_board_right`, it would look like this:
 
@@ -200,7 +197,7 @@ this might look something like:
 };
 ```
 
-See the [Keyboard Scan configuration documentation](../config/kscan.md) for details on configuring the KSCAN driver.
+See the [Keyboard Scan configuration documentation](../../config/kscan.md) for details on configuring the KSCAN driver.
 
 </TabItem>
 
@@ -301,7 +298,7 @@ This is exemplified with the iris .overlay files.
 
 ```
 
-See the [Keyboard Scan configuration documentation](../config/kscan.md) for details on configuring the KSCAN driver.
+See the [Keyboard Scan configuration documentation](../../config/kscan.md) for details on configuring the KSCAN driver.
 
 ### .conf files (Split Shields)
 
@@ -320,7 +317,7 @@ CONFIG_ZMK_SLEEP=y
 ```
 
 :::note
-The shared configuration in `my_awesome_split_board.conf` is only applied when you are building with a [`zmk-config` folder](build-flash#building-from-zmk-config-folder) and when it is present at `config/my_awesome_split_board.conf`. If you are not using a `zmk-config` folder, you will need to include the shared configuration in both `my_awesome_split_board_left.conf` and `my_awesome_split_board_right.conf` files.
+The shared configuration in `my_awesome_split_board.conf` is only applied when you are building with a [`zmk-config` folder](../local-toolchain/build-flash.mdx#building-from-zmk-config-folder) and when it is present at `config/my_awesome_split_board.conf`. If you are not using a `zmk-config` folder, you will need to include the shared configuration in both `my_awesome_split_board_left.conf` and `my_awesome_split_board_right.conf` files.
 :::
 
 </TabItem>
@@ -374,7 +371,7 @@ Some important things to note:
 - `RC(row, column)` is placed sequentially to define what row and column values that position corresponds to.
 - If you have a keyboard with options for `2u` keys in certain positions, ANSI vs. ISO layouts, or break away portions, define one matrix transform for each possible arrangement to be used in the physical layouts. This will allow the users to select the right layout in their keymap files.
 
-See the [matrix transform section](../config/kscan.md#matrix-transform) in the Keyboard Scan configuration documentation for details and more examples of matrix transforms.
+See the [matrix transform section](../../config/kscan.md#matrix-transform) in the Keyboard Scan configuration documentation for details and more examples of matrix transforms.
 
 ## Physical Layout
 
@@ -443,7 +440,7 @@ The two `#include` lines at the top of the keymap are required in order to bring
 
 ### Keymap Behaviors
 
-For documentation on the available behaviors for use in keymaps, see the [overview page for behaviors](../keymaps/behaviors/index.mdx).
+For documentation on the available behaviors for use in keymaps, see the [overview page for behaviors](../../keymaps/behaviors/index.mdx).
 
 ## Metadata
 
@@ -469,7 +466,7 @@ siblings:
   - corne_right
 ```
 
-You should place a properly named `foo.zmk.yml` file in the directory next to your other shield values, and fill it out completely and accurately. See [Hardware Metadata Files](/docs/development/hardware-metadata-files) for the full details.
+You should place a properly named `foo.zmk.yml` file in the directory next to your other shield values, and fill it out completely and accurately. See [Hardware Metadata Files](hardware-metadata-files.md) for the full details.
 
 ## Build File
 
@@ -567,7 +564,7 @@ Once you have defined the encoder sensors, you will have to add them to the list
 
 In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap.
 
-In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../config/encoders.md#devicetree) for more details.
+In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../../config/encoders.md#devicetree) for more details.
 
 </TabItem>
 <TabItem value = "overlay">
@@ -591,7 +588,7 @@ Add the following line to your keymap file to add default encoder behavior bindi
 sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>;
 ```
 
-Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../features/encoders.md) and [Keymaps](../keymaps/index.mdx) documentation pages for more details.
+Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../../features/encoders.md) and [Keymaps](../../keymaps/index.mdx) documentation pages for more details.
 
 </TabItem>
 </Tabs>
@@ -600,7 +597,7 @@ Add additional bindings as necessary to match the default number of encoders on
 
 ### GitHub Actions
 
-Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup/index.md),
+Using GitHub Actions to build your new firmware can save you from doing any local [development setup](../local-toolchain/setup/index.md),
 at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
 
 - Add all your pending changes with `git add .`
@@ -612,7 +609,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste
 ### Local Build
 
 :::note
-To build locally, be sure you've followed the [development setup](./setup/index.md) guide first.
+To build locally, be sure you've followed the [development setup](../local-toolchain/setup/index.md) guide first.
 :::
 
 Once you've fully created the new keyboard shield definition,
@@ -623,7 +620,7 @@ west build --pristine -b nice_nano_v2 -- -DSHIELD=<my_shield> -DZMK_EXTRA_MODULE
 # replace <my_shield> with e.g. <my_shield>_left for split keyboards, then repeat for <my_shield>_right
 ```
 
-The above build command generates a `build/zephyr/zmk.uf2` file that you can flash using the steps from the following section. See the dedicated [building and flashing page](build-flash.mdx) for more details.
+The above build command generates a `build/zephyr/zmk.uf2` file that you can flash using the steps from the following section. See the dedicated [building and flashing page](../local-toolchain/build-flash.mdx) for more details.
 
 ### Flashing
 
@@ -642,9 +639,9 @@ west flash
 ```
 
 Please have a look at documentation specific to
-[building and flashing](build-flash.mdx) for additional information.
+[building and flashing](../local-toolchain/build-flash.mdx) for additional information.
 
 :::note
 Further testing your keyboard shield without altering the root keymap file can be done with the use of `-DZMK_CONFIG` in your `west build` command,
-shown [here](build-flash.mdx#building-from-zmk-config-folder)
+shown [here](../local-toolchain/build-flash.mdx#building-from-zmk-config-folder)
 :::
diff --git a/docs/docs/development/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx
index cfcb39ee31..464cf34d72 100644
--- a/docs/docs/development/build-flash.mdx
+++ b/docs/docs/development/local-toolchain/build-flash.mdx
@@ -95,7 +95,7 @@ west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Use
 
 ### Building from `zmk-config` Folder
 
-Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../user-setup.mdx#github-repo) by adding
+Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../../user-setup.mdx#github-repo) by adding
 `-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
 
 For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this:
@@ -109,7 +109,7 @@ The above command must still be invoked from the `zmk/app` directory as noted ab
 :::
 
 :::warning
-If your config is also a [module](../features/modules.mdx), then you should also add the root (the folder in which the `zephyr` folder is found) of your `zmk-config` as an [external module to build with](#building-with-external-modules).
+If your config is also a [module](../../features/modules.mdx), then you should also add the root (the folder in which the `zephyr` folder is found) of your `zmk-config` as an [external module to build with](#building-with-external-modules).
 :::
 
 In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config`
diff --git a/docs/docs/development/ide-integration.mdx b/docs/docs/development/local-toolchain/ide-integration.mdx
index cee12f4b3b..cee12f4b3b 100644
--- a/docs/docs/development/ide-integration.mdx
+++ b/docs/docs/development/local-toolchain/ide-integration.mdx
diff --git a/docs/docs/development/posix-board.md b/docs/docs/development/local-toolchain/posix-board.md
index 5a809c02cc..5a809c02cc 100644
--- a/docs/docs/development/posix-board.md
+++ b/docs/docs/development/local-toolchain/posix-board.md
diff --git a/docs/docs/development/pre-commit.md b/docs/docs/development/local-toolchain/pre-commit.md
index b4306fc952..b4306fc952 100644
--- a/docs/docs/development/pre-commit.md
+++ b/docs/docs/development/local-toolchain/pre-commit.md
diff --git a/docs/docs/development/setup/docker.md b/docs/docs/development/local-toolchain/setup/docker.md
index 767331e409..8d9f94bc8a 100644
--- a/docs/docs/development/setup/docker.md
+++ b/docs/docs/development/local-toolchain/setup/docker.md
@@ -25,7 +25,7 @@ git clone https://github.com/zmkfirmware/zmk.git
 
 Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
 
-![VS Code Dev Container Configuration Alert](../../assets/dev-setup/vscode_devcontainer.png)
+![VS Code Dev Container Configuration Alert](../../../assets/dev-setup/vscode_devcontainer.png)
 
 Click `Reopen in Container` in order to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing `ctrl+shift+p` and selecting `Remote: Show Remote Menu`.
 
diff --git a/docs/docs/development/setup/index.md b/docs/docs/development/local-toolchain/setup/index.md
index 5c795fa22c..71cc051e5a 100644
--- a/docs/docs/development/setup/index.md
+++ b/docs/docs/development/local-toolchain/setup/index.md
@@ -11,10 +11,10 @@ We recommend reading through the setup process before following it step by step,
 
 There are two ways to set up the ZMK development environment:
 
-- [Docker](/docs/development/setup/docker): \
+- [Docker](docker.md): \
   A self-contained development environment. It uses the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach may be easier to set up for some operating systems. No toolchain or dependencies are necessary when using Docker; the container image has the toolchain installed and set up to use.
 
-- [Native](/docs/development/setup/native):\
+- [Native](native.mdx):\
   This uses your operating system directly. Usually runs slightly faster than the Docker approach, and can be preferable for users who already have the dependencies on their system.
 
-Please see the [Docker](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup.
+Please see the [Docker](docker.md) instructions or [native](native.mdx) instructions to continue setup.
diff --git a/docs/docs/development/setup/native.mdx b/docs/docs/development/local-toolchain/setup/native.mdx
index 40c1bbed6e..40c1bbed6e 100644
--- a/docs/docs/development/setup/native.mdx
+++ b/docs/docs/development/local-toolchain/setup/native.mdx
diff --git a/docs/docs/development/tests.md b/docs/docs/development/local-toolchain/tests.md
index 37b52bdd19..37b52bdd19 100644
--- a/docs/docs/development/tests.md
+++ b/docs/docs/development/local-toolchain/tests.md
diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx
index 65f0f60bd2..3d50b821ca 100644
--- a/docs/docs/development/new-behavior.mdx
+++ b/docs/docs/development/new-behavior.mdx
@@ -1,11 +1,15 @@
 ---
 title: New Behavior
-sidebar_label: New Behavior
+sidebar_label: New Behavior Guide
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
+:::danger
+Before reading this section, it is **vital** that you read through our [clean room policy](./contributing/clean-room.md).
+:::
+
 ## Overview
 
 This document outlines how to develop a [behavior](../keymaps/behaviors/index.mdx) for ZMK and prepare the changes for a pull request.
@@ -432,7 +436,7 @@ Zephyr currently does not support logging over Bluetooth, so any use of the seri
 
 :::info
 
-- See [Tests](tests.md) for more information on how to create virtual test sets.
+- See [Tests](local-toolchain/tests.md) for more information on how to create virtual test sets.
 - For hardware-based testing, see [USB Logging](usb-logging.mdx).
 
 :::
@@ -450,7 +454,7 @@ Consider the following prompts when writing documentation for new behaviors:
 Consider also including visual aids alongside written documentation if it adds clarity.
 
 :::info
-See [Documentation](documentation.md) for more information on writing, testing, and formatting ZMK documentation.
+See [Documentation](contributing/documentation.md) for more information on writing, testing, and formatting ZMK documentation.
 :::
 
 ## Submitting a Pull Request
diff --git a/docs/docs/development/studio-rpc-protocol.md b/docs/docs/development/studio-rpc-protocol.md
index f352a174ff..da737a131d 100644
--- a/docs/docs/development/studio-rpc-protocol.md
+++ b/docs/docs/development/studio-rpc-protocol.md
@@ -8,6 +8,10 @@ ZMK Studio is still in active development, and the below information is for deve
 
 :::
 
+:::danger
+Before reading this section, it is **vital** that you read through our [clean room policy](./contributing/clean-room.md).
+:::
+
 ## Overview
 
 The ZMK Studio UI communicates with ZMK devices using a custom RPC protocol developed to be robust and reliable, while remaining simple and easy to extend with future enhancements.
diff --git a/docs/docs/features/encoders.md b/docs/docs/features/encoders.md
index cc5bb708d4..046973f478 100644
--- a/docs/docs/features/encoders.md
+++ b/docs/docs/features/encoders.md
@@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig
 
 ## Adding Encoder Support
 
-See the [New Keyboard Shield](../development/new-shield.mdx#encoders) documentation for how to add or modify additional encoders to your shield.
+See the [New Keyboard Shield](../development/hardware-integration/new-shield.mdx#encoders) documentation for how to add or modify additional encoders to your shield.
diff --git a/docs/docs/features/modules.mdx b/docs/docs/features/modules.mdx
index acab84c2c3..5cc6e3d1c9 100644
--- a/docs/docs/features/modules.mdx
+++ b/docs/docs/features/modules.mdx
@@ -113,7 +113,7 @@ manifest:
 
 ### Building Locally
 
-To add a module to your build when building locally, you will need to clone/copy said module into your local file tree. You can then build using the module as described in [Building with External Modules](../development/build-flash.mdx#building-with-external-modules).
+To add a module to your build when building locally, you will need to clone/copy said module into your local file tree. You can then build using the module as described in [Building with External Modules](../development/local-toolchain/build-flash.mdx#building-with-external-modules).
 
 ## Beta Testing
 
@@ -191,4 +191,4 @@ manifest:
 
 ### Building Locally
 
-When building from a pull request locally, you'll need to [perform the local user setup](../development/setup/index.md), but using the repository of the pull request rather than the official ZMK repository. You can then [build and flash](../development/build-flash.mdx) as usual.
+When building from a pull request locally, you'll need to [perform the local user setup](../development/local-toolchain/setup/index.md), but using the repository of the pull request rather than the official ZMK repository. You can then [build and flash](../development/local-toolchain/build-flash.mdx) as usual.
diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md
index 7421d1d667..8c69d51a8d 100644
--- a/docs/docs/features/split-keyboards.md
+++ b/docs/docs/features/split-keyboards.md
@@ -30,7 +30,7 @@ You can refer to the [power profiler](/power-profiler) to see battery life estim
 
 ### Configuration
 
-The [new shield guide](../development/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part.
+The [new shield guide](../development/hardware-integration/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part.
 
 Also see the reference section on [split keyboards configuration](../config/system.md#split-keyboards) where the relevant symbols include `CONFIG_ZMK_SPLIT` that enables the feature, `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` which sets the central role and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` that sets the number of peripherals.
 
diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx
index 4e45286812..09f98c84eb 100644
--- a/docs/docs/hardware.mdx
+++ b/docs/docs/hardware.mdx
@@ -55,4 +55,4 @@ Please see pages under the "Features" header in the sidebar for details.
 {/* prettier-ignore */}
 <Heading as="h2" id="contributing">Contributing</Heading>
 
-If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield.mdx) documentation and note the [clean room design requirements](development/clean-room.md).
+If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/contributing/clean-room.md).
diff --git a/docs/docs/user-setup-cli.mdx b/docs/docs/user-setup-cli.mdx
index ecb0dd23af..d486d7635a 100644
--- a/docs/docs/user-setup-cli.mdx
+++ b/docs/docs/user-setup-cli.mdx
@@ -187,7 +187,7 @@ Run `zmk keyboard list` to print a list of supported keyboard hardware.
 
 If ZMK doesn't support your keyboard yet, you can run `zmk keyboard new` to create a new keyboard from a template.
 
-This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](development/new-shield.mdx) guide for how to finish writing the keyboard files.
+This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) guide for how to finish writing the keyboard files.
 
 ### Module Management
 
diff --git a/docs/docs/user-setup.mdx b/docs/docs/user-setup.mdx
index fb83ba6261..9f0dd1ce77 100644
--- a/docs/docs/user-setup.mdx
+++ b/docs/docs/user-setup.mdx
@@ -112,7 +112,7 @@ If you are building firmware for a new keyboard that is not included in the buil
 list of keyboards, you can choose any keyboard from the list that is similar to yours
 (e.g. in terms of unibody/split and [onboard controller](hardware.mdx#onboard) /
 [composite](hardware.mdx#composite)) to generate the repository,
-and edit / add necessary files. You can follow the [new shield guide](development/new-shield.mdx) if you are adding support for a composite keyboard.
+and edit / add necessary files. You can follow the [new shield guide](development/hardware-integration/new-shield.mdx) if you are adding support for a composite keyboard.
 :::
 
 ### MCU Board Selection
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
index b4e3449a95..575282406d 100644
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -81,7 +81,7 @@ module.exports = {
             },
             {
               label: "Development",
-              to: "docs/development/setup",
+              to: "docs/development/contributing/clean-room",
             },
           ],
         },
diff --git a/docs/sidebars.js b/docs/sidebars.js
index c52d6f091b..da619e5ec4 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -116,36 +116,53 @@ module.exports = {
     },
     {
       Development: [
-        "development/clean-room",
-        "development/pre-commit",
-        "development/documentation",
         {
           type: "category",
-          label: "Setup",
-          link: {
-            type: "doc",
-            id: "development/setup/index",
-          },
+          label: "Hardware Integration",
           collapsed: true,
-          items: ["development/setup/docker", "development/setup/native"],
+          items: [
+            "development/hardware-integration/new-shield",
+            "development/hardware-integration/hardware-metadata-files",
+            "development/hardware-integration/boards-shields-keymaps",
+          ],
+        },
+        {
+          type: "category",
+          label: "Contributing",
+          collapsed: true,
+          items: [
+            "development/contributing/clean-room",
+            "development/contributing/documentation",
+          ],
         },
-        "development/build-flash",
-        "development/boards-shields-keymaps",
-        "development/posix-board",
-        "development/tests",
-        "development/usb-logging",
-        "development/ide-integration",
-        "development/studio-rpc-protocol",
         {
           type: "category",
-          label: "Guides",
-          collapsed: false,
+          label: "Local Toolchain",
+          collapsed: true,
           items: [
-            "development/new-shield",
-            "development/hardware-metadata-files",
-            "development/new-behavior",
+            {
+              type: "category",
+              label: "Setup",
+              link: {
+                type: "doc",
+                id: "development/local-toolchain/setup/index",
+              },
+              collapsed: true,
+              items: [
+                "development/local-toolchain/setup/docker",
+                "development/local-toolchain/setup/native",
+              ],
+            },
+            "development/local-toolchain/build-flash",
+            "development/local-toolchain/pre-commit",
+            "development/local-toolchain/ide-integration",
+            "development/local-toolchain/tests",
+            "development/local-toolchain/posix-board",
           ],
         },
+        "development/usb-logging",
+        "development/studio-rpc-protocol",
+        "development/new-behavior",
       ],
     },
   ],
diff --git a/docs/static/_redirects b/docs/static/_redirects
index 2113e0d997..f5e8da2602 100644
--- a/docs/static/_redirects
+++ b/docs/static/_redirects
@@ -5,4 +5,16 @@
 /docs/features/encoders /docs/keymaps/encoders 301
 /docs/codes/modifiers /docs/keymaps/modifiers 301
 /docs/codes/* /docs/keymaps/list-of-keycodes 301
-/docs/features/beta-testing /docs/features/modules#beta-testing 301
\ No newline at end of file
+/docs/features/beta-testing /docs/features/modules#beta-testing 301
+/docs/development/setup /docs/development/local-toolchain/setup 301
+/docs/development/boards-shields-keymaps /docs/development/hardware-integration/boards-shields-keymaps 301
+/docs/development/hardware-metadata-files /docs/development/hardware-integration/hardware-metadata-files 301
+/docs/development/clean-room /docs/development/contributing/clean-room 301
+/docs/development/documentation /docs/development/contributing/documentation 301
+/docs/development/new-shield /docs/development/hardware-integration/new-shield 301
+/docs/development/build-flash /docs/development/local-toolchain/build-flash 301
+/docs/development/ide-integration /docs/development/local-toolchain/ide-integration 301
+/docs/development/posix-board /docs/development/local-toolchain/posix-board 301
+/docs/development/pre-commit /docs/development/local-toolchain/pre-commit 301
+/docs/development/tests /docs/development/local-toolchain/tests 301
+/docs/development/guides/new-behavior /docs/development/new-behavior 301
\ No newline at end of file