Branch point for 2026q1 Breaking Change.

Format code according to conventions

.github/workflows/api.yml

@@ -25,7 +25,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 1
         persist-credentials: false

.github/workflows/auto_tag.yml

@@ -28,7 +28,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
 

.github/workflows/bootstrap_testing.yml

@@ -0,0 +1,247 @@
+name: Bootstrap Script Testing
+
+on:
+  push:
+    branches: [master, develop, xap]
+    paths:
+      - "util/env-bootstrap.sh"
+      - ".github/workflows/bootstrap_testing.yml"
+  pull_request:
+    paths:
+      - "util/env-bootstrap.sh"
+      - ".github/workflows/bootstrap_testing.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  bootstrap-test-linux:
+    name: Bootstrap (Linux)
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        distribution:
+          # Ubuntu/Debian based
+          - debian:11
+          - debian:12
+          - debian:13
+          - ubuntu:20.04
+          - ubuntu:22.04
+          - ubuntu:24.04
+
+          # RHEL/CentOS/Fedora based
+          - fedora:41
+          - fedora:42
+          - fedora:43
+          - rockylinux:8
+          - rockylinux:9
+          - rockylinux/rockylinux:10
+          - almalinux:8
+          - almalinux:9
+          - almalinux:10
+
+          # OpenSUSE based (we skip Tumbleweed as it has issues with package versions between pattern installs and other dependencies preinstalled into the base container)
+          - opensuse/leap:latest
+
+          # Gentoo-based
+          - gentoo/stage3:latest
+
+          # Arch based
+          - archlinux:latest
+          - cachyos/cachyos:latest
+          - manjarolinux/base:latest
+
+    container:
+      image: ${{ matrix.distribution }}
+      options: --privileged
+
+    steps:
+      - name: Install base dependencies
+        run: |
+          # Attempt to run the package installation up to 10 times to mitigate transient network issues
+          for n in $(seq 1 10); do
+            {
+              echo "Attempt #$n of 10 to install base dependencies:"
+              case "${{ matrix.distribution }}" in
+                *ubuntu*|*debian*)
+                  apt-get update
+                  apt-get install -y sudo git passwd
+                  ;;
+                *fedora*|*rockylinux*|*almalinux*)
+                  dnf install -y sudo git passwd findutils  # findutils=xargs
+                  ;;
+                *suse*)
+                  zypper --non-interactive refresh
+                  zypper --non-interactive install sudo git shadow findutils  # findutils=xargs
+                  ;;
+                *gentoo*)
+                  emerge-webrsync
+                  emerge --noreplace --ask=n sudo dev-vcs/git shadow findutils  # findutils=xargs
+                  ;;
+                *archlinux*|*cachyos*|*manjaro*)
+                  pacman -Syu --noconfirm
+                  pacman -S --noconfirm sudo git
+                  ;;
+              esac
+            } && break || sleep 10
+          done
+
+          # Fix PAM configuration for sudo in containers
+          # Fix /etc/shadow permissions - common issue in container environments
+          chmod 640 /etc/shadow || chmod 400 /etc/shadow || true
+
+          # Disable problematic PAM modules that commonly fail in RHEL-like containers
+          sed -i 's/^session.*pam_systemd.so/#&/' /etc/pam.d/sudo || true
+          sed -i 's/^session.*pam_loginuid.so/#&/' /etc/pam.d/sudo || true
+
+          # Ensure proper sudoers configuration
+          echo 'Defaults !requiretty' >> /etc/sudoers
+          echo 'Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"' >> /etc/sudoers
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          submodules: recursive
+          path: qmk_firmware
+
+      - name: Create test user
+        run: |
+          # Create a test user for the bootstrap script
+          useradd -m -s /bin/bash -U testuser
+          echo 'testuser:testpassword' | chpasswd || true
+          
+          # Configure passwordless sudo
+          echo "root ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers  # some distros complain about root not being in sudoers
+          echo "testuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+          
+          # Test sudo functionality
+          sudo -u testuser whoami || echo "Sudo test failed, but continuing..."
+
+      - name: Move QMK repository to test user home
+        run: |
+          # Add upstream remote to the cloned repository so `qmk doctor` doesn't flag a warning
+          git -C qmk_firmware remote add upstream https://github.com/qmk/qmk_firmware.git
+          # Move the QMK repository to the test user's home directory
+          mv qmk_firmware /home/testuser/qmk_firmware
+          chown -R testuser:testuser /home/testuser/qmk_firmware
+
+      - name: Run bootstrap script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Ensure the bootstrap script can access sudo
+          sudo -u testuser --preserve-env=GITHUB_TOKEN bash -c "
+            export CONFIRM=1
+            export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+            cd /home/testuser
+            bash /home/testuser/qmk_firmware/util/env-bootstrap.sh
+          "
+
+      - name: Test QMK CLI
+        run: |
+          sudo -u testuser bash -c "
+            export PATH=/home/testuser/.local/bin:\$PATH
+            cd /home/testuser
+            qmk setup -y -H /home/testuser/qmk_firmware  # setup implies doctor, no need to run it separately
+            cd /home/testuser/qmk_firmware
+            qmk mass-compile -j $(nproc) -e DUMP_CI_METADATA=yes -f 'keyboard_name==*onekey*' -km reset -p || touch .failed  # Compile a bunch of different platforms
+          "
+          
+          cd /home/testuser/qmk_firmware
+          ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+          [ ! -e .failed ] || exit 1
+
+  bootstrap-test-macos:
+    name: Bootstrap (macOS)
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - macos-14        # Apple Silicon ARM64
+          - macos-15        # Apple Silicon ARM64
+          - macos-15-intel  # Intel x64
+          - macos-26        # Apple Silicon ARM64
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Run bootstrap script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Add upstream remote to the cloned repository so `qmk doctor` doesn't flag a warning
+          git remote add upstream https://github.com/qmk/qmk_firmware.git
+          # Run the bootstrap script
+          export CONFIRM=1
+          sh ./util/env-bootstrap.sh
+
+      - name: Test QMK CLI
+        run: |
+          # Add QMK CLI to PATH (bootstrap script installs it to ~/.local/bin on macOS)
+          export PATH="$HOME/.local/bin:$PATH"
+          qmk setup -y -H .  # setup implies doctor, no need to run it separately
+          qmk mass-compile -j $(sysctl -n hw.ncpu) -e DUMP_CI_METADATA=yes -f 'keyboard_name==*onekey*' -km reset || touch .failed  # Compile a bunch of different platforms
+          
+          ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+          [ ! -e .failed ] || exit 1
+
+  bootstrap-test-windows:
+    name: Bootstrap (Windows)
+
+    strategy:
+      fail-fast: false
+      matrix:
+        msys-variant:
+          - mingw64
+          - clang64
+          - ucrt64
+
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+
+    steps:
+      - name: Install MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: ${{ matrix.msys-variant }}
+          pacboy: >-
+            git:
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Run bootstrap script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Add upstream remote to the cloned repository so `qmk doctor` doesn't flag a warning
+          git remote add upstream https://github.com/qmk/qmk_firmware.git
+          # Run the bootstrap script
+          export CONFIRM=1
+          sh ./util/env-bootstrap.sh
+
+      - name: Test QMK CLI
+        run: |
+          # Add QMK CLI to PATH (bootstrap script installs it to /opt/uv/tools/bin on Windows MSYS2)
+          export PATH="/opt/uv/tools/bin:$PATH"
+          qmk setup -y -H .  # setup implies doctor, no need to run it separately
+          qmk mass-compile -j $(nproc) -e DUMP_CI_METADATA=yes -f 'keyboard_name==*onekey*' -km reset || touch .failed  # Compile a bunch of different platforms
+          
+          ./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
+          [ ! -e .failed ] || exit 1
+

.github/workflows/ci_build_major_branch.yml

@@ -6,13 +6,13 @@ permissions:
 
 on:
   push:
-    branches: [master, develop]
+    branches: [master, develop, xap]
   workflow_dispatch:
     inputs:
       branch:
         type: choice
         description: "Branch to build"
-        options: [master, develop]
+        options: [master, develop, xap]
 
 env:
   # https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits
@@ -45,14 +45,14 @@ jobs:
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Determine concurrency
         id: generate_slice_length
         run: |
           target_count=$( {
             qmk find -km default 2>/dev/null
-            # qmk find -km xap 2>/dev/null
+            qmk find -km xap 2>/dev/null
           } | sort | uniq | wc -l)
           slice_length=$((target_count / ($CONCURRENT_JOBS - 1))) # Err on the side of caution
           echo "slice_length=$slice_length" >> $GITHUB_OUTPUT
@@ -63,8 +63,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        keymap: [default]
+        keymap: [default, xap]
-        # keymap: [default, xap]
     uses: ./.github/workflows/ci_build_major_branch_keymap.yml
     with:
       branch: ${{ inputs.branch || github.ref_name }}
@@ -83,12 +82,12 @@ jobs:
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Download firmwares
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v6
         with:
           pattern: firmware-*
           path: .

.github/workflows/ci_build_major_branch_keymap.yml

@@ -37,7 +37,7 @@ jobs:
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Generate build targets
         id: generate_targets
@@ -62,7 +62,7 @@ jobs:
           echo "targets=$(jq -c 'keys' targets.json)" >> $GITHUB_OUTPUT
 
       - name: Upload targets json
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: targets-${{ inputs.keymap }}
           path: targets.json
@@ -89,10 +89,10 @@ jobs:
           git config --global --add safe.directory '*'
 
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Get target definitions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v6
         with:
           name: targets-${{ inputs.keymap }}
           path: .
@@ -112,7 +112,7 @@ jobs:
           qmk mass-compile -t -j $NCPUS -e DUMP_CI_METADATA=yes $(jq -r '.["${{ matrix.target }}"].targets' targets.json) || touch .failed
 
       - name: Upload binaries
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: firmware-${{ inputs.keymap }}-${{ matrix.target }}
           if-no-files-found: ignore
@@ -136,17 +136,17 @@ jobs:
 
     steps:
       - name: Checkout QMK Firmware
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Download firmwares
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v6
         with:
           pattern: firmware-${{ inputs.keymap }}-*
           path: .
           merge-multiple: true
 
       - name: Upload all firmwares
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: firmware-${{ inputs.keymap }}
           if-no-files-found: ignore

.github/workflows/cli.yml

@@ -24,7 +24,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         submodules: recursive
 

.github/workflows/develop_update.yml

@@ -15,7 +15,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}
         fetch-depth: 0

.github/workflows/docs.yml

@@ -30,7 +30,7 @@ jobs:
     container: ghcr.io/qmk/qmk_cli
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 1
 
@@ -56,7 +56,7 @@ jobs:
 
     - name: Deploy
       if: ${{ github.event_name == 'push' && github.repository == 'qmk/qmk_firmware' }}
-      uses: JamesIves/github-pages-deploy-action@v4.7.3
+      uses: JamesIves/github-pages-deploy-action@v4.7.4
       with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: gh-pages

.github/workflows/feature_branch_update.yml

@@ -21,7 +21,7 @@ jobs:
         - riot
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}
         fetch-depth: 0

.github/workflows/format.yml

@@ -26,7 +26,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
 
@@ -36,7 +36,7 @@ jobs:
 
     - name: Get changed files
       id: file_changes
-      uses: tj-actions/changed-files@v46
+      uses: tj-actions/changed-files@v47
       with:
         use_rest_api: true
 

.github/workflows/format_push.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
 

.github/workflows/labeler.yml

@@ -10,4 +10,4 @@ jobs:
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/labeler@v5
+    - uses: actions/labeler@v6

.github/workflows/lint.yml

@@ -18,7 +18,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
 
@@ -27,7 +27,7 @@ jobs:
 
     - name: Get changed files
       id: file_changes
-      uses: tj-actions/changed-files@v46
+      uses: tj-actions/changed-files@v47
       with:
         use_rest_api: true
 

.github/workflows/regen.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Run qmk generators
       run: |

.github/workflows/regen_push.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Disable safe.directory check
       run : git config --global --add safe.directory '*'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Run qmk generators
       run: |

.github/workflows/unit_test.yml

@@ -26,7 +26,7 @@ jobs:
     container: ghcr.io/qmk/qmk_cli
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         submodules: recursive
     - name: Install dependencies

.gitignore

@@ -64,6 +64,7 @@ build/
 cmake-build-debug
 CMakeLists.txt
 *.pdf
+*.zip
 
 # Let these ones be user specific, since we have so many different configurations
 *.code-workspace
@@ -94,6 +95,11 @@ tags
 *.mpeg
 *.ttf
 *.otf
+# Un-ignore limited image file formats in docs
+!docs/public/**.gif
+!docs/public/**.jpg
+!docs/public/**.jpeg
+!docs/public/**.png
 
 # Things Travis sees
 /.vs

Makefile

@@ -115,7 +115,7 @@ endef
 TRY_TO_MATCH_RULE_FROM_LIST = $(eval $(call TRY_TO_MATCH_RULE_FROM_LIST_HELPER,$1))$(RULE_FOUND)
 
 # As TRY_TO_MATCH_RULE_FROM_LIST_HELPER, but with additional
-# resolution of DEFAULT_FOLDER and keyboard_aliases.hjson for provided rule 
+# resolution of keyboard_aliases.hjson for provided rule 
 define TRY_TO_MATCH_RULE_FROM_LIST_HELPER_KB
     # Split on ":", padding with empty strings to avoid indexing issues
     TOKEN1:=$$(shell python3 -c "import sys; print((sys.argv[1].split(':',1)+[''])[0])" $$(RULE))
@@ -255,7 +255,7 @@ endef
 # if we are going to compile all keyboards, match the rest of the rule
 # for each of them
 define PARSE_ALL_KEYBOARDS
-    $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(shell $(QMK_BIN) list-keyboards --no-resolve-defaults)))
+    $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(shell $(QMK_BIN) list-keyboards)))
 endef
 
 # Prints a list of all known keymaps for the given keyboard
@@ -447,7 +447,7 @@ git-submodules: git-submodule
 
 .PHONY: list-keyboards
 list-keyboards:
-	$(QMK_BIN) list-keyboards --no-resolve-defaults | tr '\n' ' '
+	$(QMK_BIN) list-keyboards | tr '\n' ' '
 
 .PHONY: list-tests
 list-tests:
@@ -455,7 +455,7 @@ list-tests:
 
 .PHONY: generate-keyboards-file
 generate-keyboards-file:
-	$(QMK_BIN) list-keyboards --no-resolve-defaults
+	$(QMK_BIN) list-keyboards
 
 .PHONY: clean
 clean:

builddefs/build_json.mk

@@ -19,18 +19,18 @@ endif
 ifneq ($(QMK_USERSPACE),)
     ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/keymap.json)","")
         KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/keymap.json
-        KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)
+        KEYMAP_JSON_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)
     else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/keymap.json)","")
         KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/keymap.json
-        KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)
+        KEYMAP_JSON_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)
     else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/keymap.json)","")
         KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/keymap.json
-        KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)
+        KEYMAP_JSON_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)
     else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/keymap.json)","")
         KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/keymap.json
-        KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)
+        KEYMAP_JSON_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)
     else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/keymap.json)","")
         KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/keymap.json
-        KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)
+        KEYMAP_JSON_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)
     endif
 endif

builddefs/build_keyboard.mk

@@ -255,6 +255,8 @@ endif
 COMMUNITY_RULES_MK = $(shell $(QMK_BIN) generate-community-modules-rules-mk -kb $(KEYBOARD) --quiet --escape --output $(INTERMEDIATE_OUTPUT)/src/community_rules.mk $(KEYMAP_JSON))
 include $(COMMUNITY_RULES_MK)
 
+ifneq ($(COMMUNITY_MODULES),)
+
 $(INTERMEDIATE_OUTPUT)/src/community_modules.h: $(KEYMAP_JSON) $(DD_CONFIG_FILES)
 	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
 	$(eval CMD=$(QMK_BIN) generate-community-modules-h -kb $(KEYBOARD) --quiet --output $(INTERMEDIATE_OUTPUT)/src/community_modules.h $(KEYMAP_JSON))
@@ -289,6 +291,8 @@ SRC += $(INTERMEDIATE_OUTPUT)/src/community_modules.c
 
 generated-files: $(INTERMEDIATE_OUTPUT)/src/community_modules.h $(INTERMEDIATE_OUTPUT)/src/community_modules.c $(INTERMEDIATE_OUTPUT)/src/community_modules_introspection.c $(INTERMEDIATE_OUTPUT)/src/community_modules_introspection.h $(INTERMEDIATE_OUTPUT)/src/led_matrix_community_modules.inc $(INTERMEDIATE_OUTPUT)/src/rgb_matrix_community_modules.inc
 
+endif
+
 include $(BUILDDEFS_PATH)/converters.mk
 
 # Generate the board's version.h file.

builddefs/build_layout.mk

@@ -10,10 +10,10 @@ define SEARCH_LAYOUTS_REPO
     LAYOUT_KEYMAP_JSON := $$(LAYOUT_KEYMAP_PATH)/keymap.json
     LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c
     ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_JSON))","")
-        -include $$(LAYOUT_KEYMAP_PATH)/rules.mk
         KEYMAP_JSON := $$(LAYOUT_KEYMAP_JSON)
-        KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
+        KEYMAP_JSON_PATH := $$(LAYOUT_KEYMAP_PATH)
-    else ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
+    endif
+    ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
         -include $$(LAYOUT_KEYMAP_PATH)/rules.mk
         KEYMAP_C := $$(LAYOUT_KEYMAP_C)
         KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)

builddefs/build_test.mk

@@ -62,6 +62,7 @@ include $(BUILDDEFS_PATH)/common_features.mk
 include $(BUILDDEFS_PATH)/generic_features.mk
 include $(PLATFORM_PATH)/common.mk
 include $(TMK_PATH)/protocol.mk
+include $(QUANTUM_PATH)/battery/tests/rules.mk
 include $(QUANTUM_PATH)/debounce/tests/rules.mk
 include $(QUANTUM_PATH)/encoder/tests/rules.mk
 include $(QUANTUM_PATH)/os_detection/tests/rules.mk

builddefs/common_features.mk

@@ -29,6 +29,8 @@ QUANTUM_SRC += \
     $(QUANTUM_DIR)/logging/debug.c \
     $(QUANTUM_DIR)/logging/sendchar.c \
     $(QUANTUM_DIR)/process_keycode/process_default_layer.c \
+    $(QUANTUM_DIR)/process_keycode/process_oneshot.c \
+    $(QUANTUM_DIR)/process_keycode/process_quantum.c \
 
 include $(QUANTUM_DIR)/nvm/rules.mk
 
@@ -123,7 +125,7 @@ ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
     MOUSE_ENABLE := yes
 endif
 
-VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick azoteq_iqs5xx cirque_pinnacle_i2c cirque_pinnacle_spi paw3204 pmw3320 pmw3360 pmw3389 pimoroni_trackball custom
+VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick azoteq_iqs5xx cirque_pinnacle_i2c cirque_pinnacle_spi paw3204 paw3222 pmw3320 pmw3360 pmw3389 pimoroni_trackball custom
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     ifeq ($(filter $(POINTING_DEVICE_DRIVER),$(VALID_POINTING_DEVICE_DRIVER_TYPES)),)
         $(call CATASTROPHIC_ERROR,Invalid POINTING_DEVICE_DRIVER,POINTING_DEVICE_DRIVER="$(POINTING_DEVICE_DRIVER)" is not a valid pointing device type)
@@ -155,6 +157,8 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
             SRC += drivers/sensors/cirque_pinnacle.c
             SRC += drivers/sensors/cirque_pinnacle_gestures.c
             SRC += $(QUANTUM_DIR)/pointing_device/pointing_device_gestures.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), paw3222)
+            SPI_DRIVER_REQUIRED = yes
         else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pimoroni_trackball)
             I2C_DRIVER_REQUIRED = yes
         else ifneq ($(filter $(strip $(POINTING_DEVICE_DRIVER)),pmw3360 pmw3389),)
@@ -633,6 +637,9 @@ ifeq ($(strip $(VIA_ENABLE)), yes)
     RAW_ENABLE := yes
     BOOTMAGIC_ENABLE := yes
     TRI_LAYER_ENABLE := yes
+    ifeq ($(strip $(VIA_INSECURE)), yes)
+        OPT_DEFS += -DVIA_INSECURE
+    endif
 endif
 
 ifeq ($(strip $(RAW_ENABLE)), yes)
@@ -940,21 +947,25 @@ ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
     endif
 endif
 
+ifeq ($(strip $(BATTERY_ENABLE)), yes)
+    BATTERY_DRIVER_REQUIRED := yes
+endif
+
 VALID_BATTERY_DRIVER_TYPES := adc custom vendor
 
-BATTERY_DRIVER ?= adc
+BATTERY_DRIVER ?= none
 ifeq ($(strip $(BATTERY_DRIVER_REQUIRED)), yes)
     ifeq ($(filter $(BATTERY_DRIVER),$(VALID_BATTERY_DRIVER_TYPES)),)
         $(call CATASTROPHIC_ERROR,Invalid BATTERY_DRIVER,BATTERY_DRIVER="$(BATTERY_DRIVER)" is not a valid battery driver)
     endif
 
-    OPT_DEFS += -DBATTERY_DRIVER
+    OPT_DEFS += -DBATTERY_DRIVER_$(strip $(shell echo $(BATTERY_DRIVER) | tr '[:lower:]' '[:upper:]'))
-    OPT_DEFS += -DBATTERY_$(strip $(shell echo $(BATTERY_DRIVER) | tr '[:lower:]' '[:upper:]'))
 
     COMMON_VPATH += $(DRIVER_PATH)/battery
 
-    SRC += battery.c
+    ifneq ($(strip $(BATTERY_DRIVER)), custom)
-    SRC += battery_$(strip $(BATTERY_DRIVER)).c
+        SRC += battery_$(strip $(BATTERY_DRIVER)).c
+    endif
 
     # add extra deps
     ifeq ($(strip $(BATTERY_DRIVER)), adc)

builddefs/converters.mk

@@ -1,8 +1,3 @@
-ifneq (,$(filter $(MCU),atmega32u4))
-    # TODO: opt in rather than assume everything uses a pro micro
-    PIN_COMPATIBLE ?= promicro
-endif
-
 # Remove whitespace from any rule.mk provided vars
 #   - env cannot be overwritten but cannot have whitespace anyway
 CONVERT_TO:=$(strip $(CONVERT_TO))

builddefs/docsgen/package.json

@@ -1,7 +1,7 @@
 {
   "license": "GPL-2.0-or-later",
   "devDependencies": {
-    "vite": "^5.4.19",
+    "vite": "^5.4.21",
     "vitepress": "^1.1.0",
     "vitepress-plugin-tabs": "^0.5.0",
     "vue": "^3.4.24"

builddefs/docsgen/yarn.lock

@@ -766,10 +766,10 @@ tabbable@^6.2.0:
   resolved "https://registry.yarnpkg.com/tabbable/-/tabbable-6.2.0.tgz#732fb62bc0175cfcec257330be187dcfba1f3b97"
   integrity sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==
 
-vite@^5.2.9, vite@^5.4.19:
+vite@^5.2.9, vite@^5.4.21:
-  version "5.4.19"
+  version "5.4.21"
-  resolved "https://registry.yarnpkg.com/vite/-/vite-5.4.19.tgz#20efd060410044b3ed555049418a5e7d1998f959"
+  resolved "https://registry.yarnpkg.com/vite/-/vite-5.4.21.tgz#84a4f7c5d860b071676d39ba513c0d598fdc7027"
-  integrity sha512-qO3aKv3HoQC8QKiNSTuUM1l9o/XX3+c+VTgLHbJWHZGeTPVAg2XwazI9UWzoxjIJCGCV2zU60uqMzjeLZuULqA==
+  integrity sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==
   dependencies:
     esbuild "^0.21.3"
     postcss "^8.4.43"

builddefs/generic_features.mk

@@ -21,6 +21,7 @@ SPACE_CADET_ENABLE ?= yes
 GENERIC_FEATURES = \
     AUTO_SHIFT \
     AUTOCORRECT \
+    BATTERY \
     BOOTMAGIC \
     CAPS_WORD \
     COMBO \

builddefs/testlist.mk

@@ -1,6 +1,7 @@
 TEST_LIST = $(sort $(patsubst %/test.mk,%, $(shell find $(ROOT_DIR)tests -type f -name test.mk)))
 FULL_TESTS := $(notdir $(TEST_LIST))
 
+include $(QUANTUM_PATH)/battery/tests/testlist.mk
 include $(QUANTUM_PATH)/debounce/tests/testlist.mk
 include $(QUANTUM_PATH)/encoder/tests/testlist.mk
 include $(QUANTUM_PATH)/os_detection/tests/testlist.mk

data/constants/keycodes/keycodes_0.0.8_lighting.hjson

@@ -0,0 +1,37 @@
+{
+    "keycodes": {
+        "0x7819": {
+            "group": "led_matrix",
+            "key": "QK_LED_MATRIX_FLAG_NEXT",
+            "label": "LED Matrix Flag Next",
+            "aliases": [
+                "LM_FLGN"
+            ]
+        },
+        "0x781A": {
+            "group": "led_matrix",
+            "key": "QK_LED_MATRIX_FLAG_PREVIOUS",
+            "label": "LED Matrix Flag Previous",
+            "aliases": [
+                "LM_FLGP"
+            ]
+        },
+
+        "0x784D": {
+            "group": "rgb_matrix",
+            "key": "QK_RGB_MATRIX_FLAG_NEXT",
+            "label": "RGB Matrix Flag Next",
+            "aliases": [
+                "RM_FLGN"
+            ]
+        },
+        "0x784E": {
+            "group": "rgb_matrix",
+            "key": "QK_RGB_MATRIX_FLAG_PREVIOUS",
+            "label": "RGB Matrix Flag Previous",
+            "aliases": [
+                "RM_FLGP"
+            ]
+        }
+    }
+}

data/mappings/info_config.hjson

@@ -43,6 +43,14 @@
     "BOOTMAGIC_ROW": {"info_key": "bootmagic.matrix.0", "value_type": "int"},
     "BOOTMAGIC_ROW_RIGHT": {"info_key": "split.bootmagic.matrix.0", "value_type": "int"},
 
+    // Battery
+    "BATTERY_SAMPLE_INTERVAL": {"info_key": "battery.sample_interval", "value_type": "int"},
+    "BATTERY_ADC_PIN": {"info_key": "battery.adc.pin"},
+    "BATTERY_ADC_REF_VOLTAGE_MV": {"info_key": "battery.adc.reference_voltage", "value_type": "int"},
+    "BATTERY_ADC_VOLTAGE_DIVIDER_R1": {"info_key": "battery.adc.divider_r1", "value_type": "int"},
+    "BATTERY_ADC_VOLTAGE_DIVIDER_R2": {"info_key": "battery.adc.divider_r2", "value_type": "int"},
+    "BATTERY_ADC_RESOLUTION": {"info_key": "battery.adc.resolution", "value_type": "int"},
+
     // Caps Word
     "BOTH_SHIFTS_TURNS_ON_CAPS_WORD": {"info_key": "caps_word.both_shifts_turns_on", "value_type": "flag"},
     "CAPS_WORD_IDLE_TIMEOUT": {"info_key": "caps_word.idle_timeout", "value_type": "int"},
@@ -90,6 +98,7 @@
 
     // LED Matrix
     "LED_MATRIX_CENTER": {"info_key": "led_matrix.center_point", "value_type": "array.int"},
+    "LED_MATRIX_FLAG_STEPS": {"info_key": "led_matrix.flag_steps", "value_type": "array.int"},
     "LED_MATRIX_KEYRELEASES": {"info_key": "led_matrix.react_on_keyup", "value_type": "flag"},
     "LED_MATRIX_LED_FLUSH_LIMIT": {"info_key": "led_matrix.led_flush_limit", "value_type": "int"},
     "LED_MATRIX_LED_PROCESS_LIMIT": {"info_key": "led_matrix.led_process_limit", "value_type": "int", "to_json": false},
@@ -103,6 +112,7 @@
     "LED_MATRIX_DEFAULT_ON": {"info_key": "led_matrix.default.on", "value_type": "bool"},
     "LED_MATRIX_DEFAULT_VAL": {"info_key": "led_matrix.default.val", "value_type": "int"},
     "LED_MATRIX_DEFAULT_SPD": {"info_key": "led_matrix.default.speed", "value_type": "int"},
+    "LED_MATRIX_DEFAULT_FLAGS": {"info_key": "led_matrix.default.flags", "value_type": "int"},
 
     // Locking Switch
     "LOCKING_SUPPORT_ENABLE": {"info_key": "qmk.locking.enabled", "value_type": "flag"},
@@ -120,6 +130,7 @@
     "MATRIX_HAS_GHOST": {"info_key": "matrix_pins.ghost", "value_type": "flag"},
     "MATRIX_INPUT_PRESSED_STATE": {"info_key": "matrix_pins.input_pressed_state", "value_type": "int"},
     "MATRIX_IO_DELAY": {"info_key": "matrix_pins.io_delay", "value_type": "int"},
+    "MATRIX_MASKED": {"info_key": "matrix_pins.masked", "value_type": "flag"},
 
     // Mouse Keys
     "MOUSEKEY_DELAY": {"info_key": "mousekey.delay", "value_type": "int"},
@@ -138,6 +149,7 @@
 
     // RGB Matrix
     "RGB_MATRIX_CENTER": {"info_key": "rgb_matrix.center_point", "value_type": "array.int"},
+    "RGB_MATRIX_FLAG_STEPS": {"info_key": "rgb_matrix.flag_steps", "value_type": "array.int"},
     "RGB_MATRIX_HUE_STEP": {"info_key": "rgb_matrix.hue_steps", "value_type": "int"},
     "RGB_MATRIX_KEYRELEASES": {"info_key": "rgb_matrix.react_on_keyup", "value_type": "flag"},
     "RGB_MATRIX_LED_FLUSH_LIMIT": {"info_key": "rgb_matrix.led_flush_limit", "value_type": "int"},
@@ -155,6 +167,7 @@
     "RGB_MATRIX_DEFAULT_SAT": {"info_key": "rgb_matrix.default.sat", "value_type": "int"},
     "RGB_MATRIX_DEFAULT_VAL": {"info_key": "rgb_matrix.default.val", "value_type": "int"},
     "RGB_MATRIX_DEFAULT_SPD": {"info_key": "rgb_matrix.default.speed", "value_type": "int"},
+    "RGB_MATRIX_DEFAULT_FLAGS": {"info_key": "rgb_matrix.default.flags", "value_type": "int"},
 
     // RGBLight
     "RGBLED_SPLIT": {"info_key": "rgblight.split_count", "value_type": "array.int"},
@@ -183,7 +196,7 @@
 
     // Split Keyboard
     "SOFT_SERIAL_PIN": {"info_key": "split.serial.pin"},
-    "SOFT_SERIAL_SPEED": {"info_key": "split.soft_serial_speed"},
+    "SELECT_SOFT_SERIAL_SPEED": {"info_key": "split.serial.speed"},
     "SPLIT_HAND_MATRIX_GRID": {"info_key": "split.handedness.matrix_grid", "value_type": "array", "to_c": false},
     "SPLIT_HAND_PIN": {"info_key": "split.handedness.pin"},
     "SPLIT_USB_DETECT": {"info_key": "split.usb_detect.enabled", "value_type": "flag"},
@@ -211,6 +224,7 @@
     "PERMISSIVE_HOLD_PER_KEY": {"info_key": "tapping.permissive_hold_per_key", "value_type": "flag"},
     "RETRO_TAPPING": {"info_key": "tapping.retro", "value_type": "flag"},
     "RETRO_TAPPING_PER_KEY": {"info_key": "tapping.retro_per_key", "value_type": "flag"},
+    "SPECULATIVE_HOLD": {"info_key": "tapping.speculative_hold", "value_type": "flag"},
     "TAP_CODE_DELAY": {"info_key": "qmk.tap_keycode_delay", "value_type": "int"},
     "TAP_HOLD_CAPS_DELAY": {"info_key": "qmk.tap_capslock_delay", "value_type": "int"},
     "TAPPING_TERM": {"info_key": "tapping.term", "value_type": "int"},

data/mappings/info_defaults.hjson

@@ -23,7 +23,8 @@
             "animation": "solid",
             "on": true,
             "val": 255,
-            "speed": 128
+            "speed": 128,
+            "flags": 255
         },
         "led_flush_limit": 16,
         "max_brightness": 255,
@@ -53,7 +54,8 @@
             "hue": 0,
             "sat": 255,
             "val": 255,
-            "speed": 128
+            "speed": 128,
+            "flags": 255
         },
         "hue_steps": 8,
         "led_flush_limit": 16,

data/mappings/info_rules.hjson

@@ -13,6 +13,7 @@
 
     "AUDIO_DRIVER": {"info_key": "audio.driver"},
     "BACKLIGHT_DRIVER": {"info_key": "backlight.driver"},
+    "BATTERY_DRIVER": {"info_key": "battery.driver"},
     "BLUETOOTH_DRIVER": {"info_key": "bluetooth.driver"},
     "BOARD": {"info_key": "board"},
     "BOOTLOADER": {"info_key": "bootloader", "warn_duplicate": false},
@@ -53,8 +54,8 @@
     "WS2812_DRIVER": {"info_key": "ws2812.driver"},
 
     // Items we want flagged in lint
-    "DEFAULT_FOLDER": {"info_key": "_deprecated.default_folder", "deprecated": true},
     "CTPC": {"info_key": "_invalid.ctpc", "invalid": true, "replace_with": "CONVERT_TO=proton_c"},
     "CONVERT_TO_PROTON_C": {"info_key": "_invalid.ctpc", "invalid": true, "replace_with": "CONVERT_TO=proton_c"},
+    "DEFAULT_FOLDER": {"info_key": "_invalid.default_folder", "invalid": true},
     "VIAL_ENABLE": {"info_key": "_invalid.vial", "invalid": true}
 }

data/mappings/keyboard_aliases.hjson

@@ -68,6 +68,81 @@
     "bakeneko80": {
         "target": "kkatano/bakeneko80"
     },
+    "bastardkb/charybdis/3x5/v2/elitec": {
+        "target": "bastardkb/charybdis/3x5/elitec"
+    },
+    "bastardkb/charybdis/3x5/v2/splinky_2": {
+        "target": "bastardkb/charybdis/3x5/elitec"
+    },
+    "bastardkb/charybdis/3x5/v2/splinky_3": {
+        "target": "bastardkb/charybdis/3x5/elitec"
+    },
+    "bastardkb/charybdis/3x5/v2/stemcell": {
+        "target": "bastardkb/charybdis/3x5/elitec"
+    },
+    "bastardkb/charybdis/3x6/v2/elitec": {
+        "target": "bastardkb/charybdis/3x6/elitec"
+    },
+    "bastardkb/charybdis/3x6/v2/splinky_2": {
+        "target": "bastardkb/charybdis/3x6/elitec"
+    },
+    "bastardkb/charybdis/3x6/v2/splinky_3": {
+        "target": "bastardkb/charybdis/3x6/elitec"
+    },
+    "bastardkb/charybdis/3x6/v2/stemcell": {
+        "target": "bastardkb/charybdis/3x6/elitec"
+    },
+    "bastardkb/charybdis/4x6/v2/elitec": {
+        "target": "bastardkb/charybdis/4x6/elitec"
+    },
+    "bastardkb/charybdis/4x6/v2/splinky_2": {
+        "target": "bastardkb/charybdis/4x6/elitec"
+    },
+    "bastardkb/charybdis/4x6/v2/splinky_3": {
+        "target": "bastardkb/charybdis/4x6/elitec"
+    },
+    "bastardkb/charybdis/4x6/v2/stemcell": {
+        "target": "bastardkb/charybdis/4x6/elitec"
+    },
+    "bastardkb/dilemma/3x5_2/splinky": {
+        "target": "bastardkb/dilemma/3x5_2/promicro"
+    },
+    "bastardkb/scylla/v2/elitec": {
+        "target": "bastardkb/scylla/promicro"
+    },
+    "bastardkb/scylla/v2/splinky_2": {
+        "target": "bastardkb/scylla/promicro"
+    },
+    "bastardkb/scylla/v2/splinky_3": {
+        "target": "bastardkb/scylla/promicro"
+    },
+    "bastardkb/scylla/v2/stemcell": {
+        "target": "bastardkb/scylla/promicro"
+    },
+    "bastardkb/skeletyl/v2/elitec": {
+        "target": "bastardkb/skeletyl/promicro"
+    },
+    "bastardkb/skeletyl/v2/splinky_2": {
+        "target": "bastardkb/skeletyl/promicro"
+    },
+    "bastardkb/skeletyl/v2/splinky_3": {
+        "target": "bastardkb/skeletyl/promicro"
+    },
+    "bastardkb/skeletyl/v2/stemcell": {
+        "target": "bastardkb/skeletyl/promicro"
+    },
+    "bastardkb/tbkmini/v2/elitec": {
+        "target": "bastardkb/tbkmini/promicro"
+    },
+    "bastardkb/tbkmini/v2/splinky_2": {
+        "target": "bastardkb/tbkmini/promicro"
+    },
+    "bastardkb/tbkmini/v2/splinky_3": {
+        "target": "bastardkb/tbkmini/promicro"
+    },
+    "bastardkb/tbkmini/v2/stemcell": {
+        "target": "bastardkb/tbkmini/promicro"
+    },
     "bear_face": {
         "target": "bear_face/v1"
     },
@@ -257,44 +332,11 @@
     "handwired/jscotto/scottostarter": {
         "target": "handwired/scottokeebs/scottostarter"
     },
-    "helix/pico/sc/back": {
+    "helix": {
-        "target": "helix/pico/sc"
+        "target": "helix/beta"
     },
-    "helix/pico/sc/under": {
+    "helix/rev2": {
-        "target": "helix/pico/sc"
+        "target": "helix/beta"
-    },
-    "helix/rev2/back/oled": {
-        "target": "helix/rev2/back"
-    },
-    "helix/rev2/oled": {
-        "target": "helix/rev2"
-    },
-    "helix/rev2/oled/back": {
-        "target": "helix/rev2/back"
-    },
-    "helix/rev2/oled/under": {
-        "target": "helix/rev2/under"
-    },
-    "helix/rev2/sc/back": {
-        "target": "helix/rev2/sc"
-    },
-    "helix/rev2/sc/oled": {
-        "target": "helix/rev2/sc"
-    },
-    "helix/rev2/sc/oledback": {
-        "target": "helix/rev2/sc"
-    },
-    "helix/rev2/sc/oledunder": {
-        "target": "helix/rev2/sc"
-    },
-    "helix/rev2/sc/under": {
-        "target": "helix/rev2/sc"
-    },
-    "helix/rev2/under": {
-        "target": "helix/rev2/sc"
-    },
-    "helix/rev2/under/oled": {
-        "target": "helix/rev2/under"
     },
     "honeycomb": {
         "target": "keyhive/honeycomb"
@@ -407,6 +449,9 @@
     "lfkeyboards/smk65": {
         "target": "lfkeyboards/smk65/revb"
     },
+    "ll3macorn/bongopad": {
+        "target": "ll3ma/bongopad"
+    },
     "m3v3van": {
         "target": "matthewdias/m3n3van"
     },
@@ -1575,8 +1620,11 @@
     "0_sixty": {
         "target": "0_sixty/base"
     },
-    "0xcb/splaytoraid": {
+    "0xcb/splaytoraid/32u4": {
-        "target": "0xcb/splaytoraid/rp2040_ce"
+        "target": "0xcb/splaytoraid"
+    },
+    "0xcb/splaytoraid/rp2040_ce": {
+        "target": "0xcb/splaytoraid"
     },
     "1upkeyboards/pi40": {
         "target": "1upkeyboards/pi40/mit_v1_0"
@@ -1587,12 +1635,24 @@
     "1upkeyboards/sweet16": {
         "target": "1upkeyboards/sweet16/v1"
     },
+    "1upkeyboards/sweet16v2/kb2040": {
+        "target": "1upkeyboards/sweet16v2"
+    },
+    "1upkeyboards/sweet16v2/pro_micro": {
+        "target": "1upkeyboards/sweet16v2"
+    },
     "25keys/aleth42": {
         "target": "25keys/aleth42/rev1"
     },
     "25keys/zinc": {
         "target": "25keys/zinc/rev1"
     },
+    "40percentclub/gherkin/kb2040": {
+        "target": "40percentclub/gherkin"
+    },
+    "40percentclub/gherkin/pro_micro": {
+        "target": "40percentclub/gherkin"
+    },
     "40percentclub/i75": {
         "target": "40percentclub/i75/promicro"
     },
@@ -1690,7 +1750,7 @@
         "target": "durgod/dgk6x/galaxy"
     },
     "durgod/venus": {
-        "target": "durgod/dgk6x/venus"
+        "target": "durgod/dgk6x/venus_ansi"
     },
     "dztech/tofu/ii": {
         "target": "dztech/tofu/ii/v1"
@@ -1881,6 +1941,12 @@
     "kin80": {
         "target": "kin80/blackpill401"
     },
+    "kprepublic/cstc40/daughterboard": {
+        "target": "kprepublic/cstc40/rev1"
+    },
+    "kprepublic/cstc40/single_pcb": {
+        "target": "kprepublic/cstc40/rev2"
+    },
     "kumaokobo/kudox_full": {
         "target": "kumaokobo/kudox_full/rev1"
     },
@@ -2214,8 +2280,17 @@
     "trnthsn/s6xty5neor2": {
         "target": "trnthsn/s6xty5neor2/stm32f103"
     },
-    "tweetydabird/lotus58": {
+    "tweetydabird/lotus58/elite_c": {
-        "target": "tweetydabird/lotus58/promicro"
+        "target": "tweetydabird/lotus58"
+    },
+    "tweetydabird/lotus58/nanoboot": {
+        "target": "tweetydabird/lotus58"
+    },
+    "tweetydabird/lotus58/promicro": {
+        "target": "tweetydabird/lotus58"
+    },
+    "tweetydabird/lotus58/rp2040_ce": {
+        "target": "tweetydabird/lotus58"
     },
     "unison": {
         "target": "unison/v04"
@@ -2258,5 +2333,54 @@
     },
     "zsa/planck_ez": {
         "target": "zsa/planck_ez/base"
+    },
+    // DEFAULT_FOLDER removed during 2025 Q3 cycle
+    "cannonkeys/satisfaction75": {
+        "target": "cannonkeys/satisfaction75/rev1"
+    },
+    "converter/adb_usb": {
+        "target": "converter/adb_usb/rev1"
+    },
+    "converter/sun_usb": {
+        "target": "converter/sun_usb/type5"
+    },
+    "converter/usb_usb": {
+        "target": "converter/usb_usb/hasu"
+    },
+    "durgod/dgk6x": {
+        "target": "durgod/dgk6x/hades_ansi"
+    },
+    "ergodox_ez": {
+        "target": "ergodox_ez/base"
+    },
+    "ferris/0_2": {
+        "target": "ferris/0_2/base"
+    },
+    "handwired/dygma/raise": {
+        "target": "handwired/dygma/raise/ansi"
+    },
+    "helix/rev3_4rows": {
+        "target": "helix/rev3"
+    },
+    "helix/rev3_5rows": {
+        "target": "helix/rev3"
+    },
+    "ibm/model_m/mschwingen": {
+        "target": "ibm/model_m/mschwingen/led_wired"
+    },
+    "mechwild/sugarglider": {
+        "target": "mechwild/sugarglider/wide_oled/f401"
+    },
+    "mechwild/sugarglider/wide_oled": {
+        "target": "mechwild/sugarglider/wide_oled/f401"
+    },
+    "novelkeys/nk65": {
+        "target": "novelkeys/nk65/v1"
+    },
+    "novelkeys/nk65/base": {
+        "target": "novelkeys/nk65/v1"
+    },
+    "sirius/uni660/rev2": {
+        "target": "sirius/uni660/rev2/ansi"
     }
 }

data/schemas/keyboard.jsonschema

@@ -188,6 +188,28 @@
                 "as_caps_lock": {"type": "boolean"}
             }
         },
+        "battery": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "driver": {
+                    "type": "string",
+                    "enum": ["adc", "custom", "vendor"]
+                },
+                "adc": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "pin": {"$ref": "./definitions.jsonschema#/mcu_pin"},
+                        "reference_voltage": {"type": "integer"},
+                        "divider_r1": {"type": "integer"},
+                        "divider_r2": {"type": "integer"},
+                        "resolution": {"type": "integer"}
+                    }
+                },
+                "sample_interval": {"type": "integer"}
+            }
+        },
         "bluetooth": {
             "type": "object",
             "additionalProperties": false,
@@ -473,6 +495,7 @@
                 "ghost": {"type": "boolean"},
                 "input_pressed_state": {"$ref": "./definitions.jsonschema#/unsigned_int"},
                 "io_delay": {"$ref": "./definitions.jsonschema#/unsigned_int"},
+                "masked": {"type": "boolean"},
                 "direct": {
                     "type": "array",
                     "items": {"$ref": "./definitions.jsonschema#/mcu_pin_array"}
@@ -520,7 +543,8 @@
                         "on": {"type": "boolean"},
                         "animation": {"type": "string"},
                         "val": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
-                        "speed": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
+                        "speed": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
+                        "flags": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
                     }
                 },
                 "driver": {
@@ -548,6 +572,11 @@
                     "maxItems": 2,
                     "items": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
                 },
+                "flag_steps": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
+                },
                 "max_brightness": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
                 "timeout": {"$ref": "./definitions.jsonschema#/unsigned_int"},
                 "val_steps": {"$ref": "./definitions.jsonschema#/unsigned_int"},
@@ -603,7 +632,8 @@
                         "hue": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
                         "sat": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
                         "val": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
-                        "speed": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
+                        "speed": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
+                        "flags": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
                     }
                 },
                 "driver": {
@@ -633,6 +663,11 @@
                     "maxItems": 2,
                     "items": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
                 },
+                "flag_steps": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {"$ref": "./definitions.jsonschema#/unsigned_int_8"}
+                },
                 "max_brightness": {"$ref": "./definitions.jsonschema#/unsigned_int_8"},
                 "timeout": {"$ref": "./definitions.jsonschema#/unsigned_int"},
                 "hue_steps": {"$ref": "./definitions.jsonschema#/unsigned_int"},
@@ -863,8 +898,7 @@
                 },
                 "soft_serial_speed": {
                     "type": "integer",
-                    "minimum": 0,
+                    "$comment": "Deprecated: use split.serial.speed instead"
-                    "maximum": 5
                 },
                 "serial": {
                     "type": "object",
@@ -874,7 +908,12 @@
                             "type": "string",
                             "enum": ["bitbang", "usart", "vendor"]
                         },
-                        "pin": {"$ref": "./definitions.jsonschema#/mcu_pin"}
+                        "pin": {"$ref": "./definitions.jsonschema#/mcu_pin"},
+                        "speed": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "maximum": 5
+                        }
                     }
                 },
                 "transport": {

data/schemas/keymap.jsonschema

@@ -35,6 +35,17 @@
                 }
             }
         },
+        "dip_switches": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["on", "off"],
+                "properties": {
+                    "on": {"type": "string"},
+                    "off": {"type": "string"}
+                }
+            }
+        },
         "macros": {
             "type": "array",
             "items": {

docs/ChangeLog/20200229.md

@@ -36,7 +36,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch
 ## Encoder flip
 
 * Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise
-* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users.
+* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected direction is simple for users.
 * Cleans up documentation page for encoders
 
 

docs/ChangeLog/20200530.md

@@ -38,7 +38,7 @@ After the next breaking change you will not be able to build if `bin/qmk hello`
 [#8269](https://github.com/qmk/qmk_firmware/pull/8269)
 
 - Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations.
-- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
+- Less maintenance, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
 - A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency.
 
 ### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup
@@ -51,8 +51,10 @@ After the next breaking change you will not be able to build if `bin/qmk hello`
 
 The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200.
 
-Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100`  
+```diff
-After: `#define RGB_DISABLE_TIMEOUT 120000`
+-#define RGB_DISABLE_AFTER_TIMEOUT 100
++#define RGB_DISABLE_TIMEOUT 120000
+```
 
 ### Switch to qmk forks for everything
 

docs/ChangeLog/20210529.md

@@ -12,7 +12,7 @@ Added support for MK66F18 (Teensy 3.6) microcontroller.
 
 ### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) {#new-command-qmk-console}
 
-A new `qmk console` command has been added for attaching to your keyboard's console. It operates similiarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages.
+A new `qmk console` command has been added for attaching to your keyboard's console. It operates similarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages.
 
 ### Improved command: qmk config {#improve-command-qmk-config}
 

docs/ChangeLog/20250831.md

@@ -0,0 +1,181 @@
+# QMK Breaking Changes - 2025 Aug 31 Changelog
+
+## Changes Requiring User Action
+
+### Updated Keyboard Codebases
+
+| Old Keyboard Name                    | New Keyboard Name                |
+|--------------------------------------|----------------------------------|
+| bastardkb/charybdis/3x5/v2/elitec    | bastardkb/charybdis/3x5/elitec   |
+| bastardkb/charybdis/3x5/v2/splinky_2 | bastardkb/charybdis/3x5/elitec   |
+| bastardkb/charybdis/3x5/v2/splinky_3 | bastardkb/charybdis/3x5/elitec   |
+| bastardkb/charybdis/3x5/v2/stemcell  | bastardkb/charybdis/3x5/elitec   |
+| bastardkb/charybdis/3x6/v2/elitec    | bastardkb/charybdis/3x6/elitec   |
+| bastardkb/charybdis/3x6/v2/splinky_2 | bastardkb/charybdis/3x6/elitec   |
+| bastardkb/charybdis/3x6/v2/splinky_3 | bastardkb/charybdis/3x6/elitec   |
+| bastardkb/charybdis/3x6/v2/stemcell  | bastardkb/charybdis/3x6/elitec   |
+| bastardkb/charybdis/4x6/v2/elitec    | bastardkb/charybdis/4x6/elitec   |
+| bastardkb/charybdis/4x6/v2/splinky_2 | bastardkb/charybdis/4x6/elitec   |
+| bastardkb/charybdis/4x6/v2/splinky_3 | bastardkb/charybdis/4x6/elitec   |
+| bastardkb/charybdis/4x6/v2/stemcell  | bastardkb/charybdis/4x6/elitec   |
+| bastardkb/dilemma/3x5_2/splinky      | bastardkb/dilemma/3x5_2/promicro |
+| bastardkb/scylla/v2/elitec           | bastardkb/scylla/promicro        |
+| bastardkb/scylla/v2/splinky_2        | bastardkb/scylla/promicro        |
+| bastardkb/scylla/v2/splinky_3        | bastardkb/scylla/promicro        |
+| bastardkb/scylla/v2/stemcell         | bastardkb/scylla/promicro        |
+| bastardkb/skeletyl/v2/elitec         | bastardkb/skeletyl/promicro      |
+| bastardkb/skeletyl/v2/splinky_2      | bastardkb/skeletyl/promicro      |
+| bastardkb/skeletyl/v2/splinky_3      | bastardkb/skeletyl/promicro      |
+| bastardkb/skeletyl/v2/stemcell       | bastardkb/skeletyl/promicro      |
+| bastardkb/tbkmini/v2/elitec          | bastardkb/tbkmini/promicro       |
+| bastardkb/tbkmini/v2/splinky_2       | bastardkb/tbkmini/promicro       |
+| bastardkb/tbkmini/v2/splinky_3       | bastardkb/tbkmini/promicro       |
+| bastardkb/tbkmini/v2/stemcell        | bastardkb/tbkmini/promicro       |
+| helix/rev2                           | helix/beta                       |
+| helix/rev3_4rows                     | helix/rev3                       |
+| helix/rev3_5rows                     | helix/rev3                       |
+| kprepublic/cstc40/daughterboard      | kprepublic/cstc40/rev1           |
+| kprepublic/cstc40/single_pcb         | kprepublic/cstc40/rev2           |
+| ll3macorn/bongopad                   | ll3ma/bongopad                   |
+| novelkeys/nk65/base                  | novelkeys/nk65/v1                |
+| tweetydabird/lotus58/elite_c         | tweetydabird/lotus58             |
+| tweetydabird/lotus58/nanoboot        | tweetydabird/lotus58             |
+| tweetydabird/lotus58/promicro        | tweetydabird/lotus58             |
+| tweetydabird/lotus58/rp2040_ce       | tweetydabird/lotus58             |
+
+### Mitigate VIA keylogger security issues [#25414](https://github.com/qmk/qmk_firmware/pull/25414)
+
+VIA's keyboard matrix testing functionality, which allows users to identify active key presses, has been identified as a potential security concern by community members and security researchers. This feature has been demonstrated to enable unauthorized keystroke capture, with documented examples showing how malicious scripts could exploit this capability to create keyloggers. A recent security assessment revealed that user credentials could be compromised by exploiting the matrix testing function combined with VIA's keycode assignment queries. In this attack scenario, a script could remain active during a locked session and capture password input when users authenticate upon return.
+
+The QMK team notified the VIA team of this security vulnerability on May 17, 2022, and made multiple subsequent attempts to coordinate a mitigation strategy. Despite repeated outreach, the VIA team has provided no acknowledgment or response to these security concerns. Given the severity of the potential security implications and the lack of engagement from the VIA team, the QMK team has unilaterally implemented a security enhancement that modifies the keyboard matrix testing functionality to prevent the reporting of key press events. This change prioritizes user security and data protection over potential feature compatibility concerns within VIA.
+
+## Deprecation Notices
+
+In line with the [notice period](../support_deprecation_policy#how-much-advance-notice-will-be-given), deprecation notices for larger items are listed here.
+
+### `DEFAULT_FOLDER` removal ([#23281](https://github.com/qmk/qmk_firmware/pull/23281))
+
+`DEFAULT_FOLDER` was originally introduced to work around limitations within the build system.
+Parent folders containing common configuration would create invalid build targets.
+
+With the introduction of [`keyboard.json`](./20240526#keyboard-json) as a configuration file, the build system now has a consistent method to detect build targets.
+The `DEFAULT_FOLDER` functionality is now removed with the intent that `rules.mk` is now pure configuration.
+
+Backwards compatibility of build targets has been maintained where possible.
+
+### Converter `Pin Compatible` updates ([#20330](https://github.com/qmk/qmk_firmware/pull/20330))
+
+Converter support has been further limited to only function if a keyboard declares that it is compatible.
+
+This can be configured in the following ways:
+
+:::::tabs
+
+==== keyboard.json
+
+```json [keyboard.json]
+{
+    "development_board": "promicro", // [!code focus]
+}
+```
+
+==== rules.mk
+
+```make [rules.mk]
+PIN_COMPATIBLE = promicro
+```
+
+:::::
+
+see the [Converters Feature](../feature_converters) documentation for more information.
+
+### Removal of deprecated RGB and Mouse keycodes ([#25444](https://github.com/qmk/qmk_firmware/pull/25444))
+
+Backwards compatibility of deprecated RGB and Mouse keycodes has been removed.
+
+See the following documentation for the list of currently supported keycodes:
+
+* [RGB Lighting](../features/rgblight#keycodes)
+* [RGB Matrix](../features/rgb_matrix#keycodes)
+* [Mouse keys](../features/mouse_keys#mapping-mouse-actions)
+
+## Full changelist
+
+Core:
+* Remove converter assumption that everything is a promicro ([#20330](https://github.com/qmk/qmk_firmware/pull/20330))
+* Remove `DEFAULT_FOLDER` handling ([#23281](https://github.com/qmk/qmk_firmware/pull/23281))
+* Add core handling for pointing device failures. ([#25315](https://github.com/qmk/qmk_firmware/pull/25315))
+* Relocate remaining `process_record_quantum` keycodes ([#25328](https://github.com/qmk/qmk_firmware/pull/25328))
+* Remove `process_action_kb` callback ([#25331](https://github.com/qmk/qmk_firmware/pull/25331))
+* Add `{rgb|led}_matrix_get_mode_name()`. ([#25344](https://github.com/qmk/qmk_firmware/pull/25344))
+* Align sleep_led logic ([#25395](https://github.com/qmk/qmk_firmware/pull/25395))
+* Mitigate VIA keylogger security issues ([#25414](https://github.com/qmk/qmk_firmware/pull/25414))
+* Deprecate some nonstandard mod & mod-tap keycode aliases ([#25437](https://github.com/qmk/qmk_firmware/pull/25437))
+* Refactor Starlight Smooth matrix effect ([#25442](https://github.com/qmk/qmk_firmware/pull/25442))
+* Remove deprecated `RGB_` and Mouse keycodes ([#25444](https://github.com/qmk/qmk_firmware/pull/25444))
+* Configure SPI for `QMK_PM2040` board ([#25481](https://github.com/qmk/qmk_firmware/pull/25481))
+* Configure SPI for `STEMCELL` board ([#25486](https://github.com/qmk/qmk_firmware/pull/25486))
+* Configure SPI for `QMK_BLOK` board ([#25487](https://github.com/qmk/qmk_firmware/pull/25487))
+* Clamp reactive offset value ([#25489](https://github.com/qmk/qmk_firmware/pull/25489))
+* Relocate `AUDIO_INIT_DELAY` implementation ([#25491](https://github.com/qmk/qmk_firmware/pull/25491))
+* Add MATRIX_ROWS_PER_HAND definition ([#25513](https://github.com/qmk/qmk_firmware/pull/25513))
+* Refactor battery driver ([#25550](https://github.com/qmk/qmk_firmware/pull/25550))
+* Add cachyos as pattern when installing dependencies ([#25580](https://github.com/qmk/qmk_firmware/pull/25580))
+
+CLI:
+* Add MATRIX_MASKED DD config ([#25383](https://github.com/qmk/qmk_firmware/pull/25383))
+* Ensure keyboard aliases do not point to themselves ([#25500](https://github.com/qmk/qmk_firmware/pull/25500))
+
+Keyboards:
+* [Update] E8ghtyNeo caps indicator ([#25009](https://github.com/qmk/qmk_firmware/pull/25009))
+* Keychron C3 Pro `c3_pro.c` corrections ([#25049](https://github.com/qmk/qmk_firmware/pull/25049))
+* Update franky36 pid and vid ([#25160](https://github.com/qmk/qmk_firmware/pull/25160))
+* Added Encoder support for Soyuz ([#25279](https://github.com/qmk/qmk_firmware/pull/25279))
+* CSTC40 rev3 (FXTWINK) ([#25285](https://github.com/qmk/qmk_firmware/pull/25285))
+* Migrate remaining `DEFAULT_FOLDER` to keyboard aliases ([#25291](https://github.com/qmk/qmk_firmware/pull/25291))
+* Configure boards to use development_board - R ([#25316](https://github.com/qmk/qmk_firmware/pull/25316))
+* Configure boards to use development_board - P ([#25317](https://github.com/qmk/qmk_firmware/pull/25317))
+* Configure boards to use development_board - NO ([#25338](https://github.com/qmk/qmk_firmware/pull/25338))
+* Configure boards to use development_board - LM ([#25341](https://github.com/qmk/qmk_firmware/pull/25341))
+* maple_computing/launchpad - Remove broken `default_rgb` keymap ([#25342](https://github.com/qmk/qmk_firmware/pull/25342))
+* update winry25 VID and PID ([#25351](https://github.com/qmk/qmk_firmware/pull/25351))
+* Configure boards to use development_board - DE ([#25369](https://github.com/qmk/qmk_firmware/pull/25369))
+* Configure boards to use development_board - FGHIJ ([#25370](https://github.com/qmk/qmk_firmware/pull/25370))
+* refactor(mercutio): layouts & reformatting ([#25408](https://github.com/qmk/qmk_firmware/pull/25408))
+* Configure boards to use development_board - ABC ([#25417](https://github.com/qmk/qmk_firmware/pull/25417))
+* Configure boards to use development_board - K ([#25421](https://github.com/qmk/qmk_firmware/pull/25421))
+* Refactor `helix/pico` ([#25428](https://github.com/qmk/qmk_firmware/pull/25428))
+* Refactor `helix/rev2` ([#25429](https://github.com/qmk/qmk_firmware/pull/25429))
+* Refactor `helix/rev3_{4,5}rows` ([#25430](https://github.com/qmk/qmk_firmware/pull/25430))
+* Migrate `helix` common configuration ([#25433](https://github.com/qmk/qmk_firmware/pull/25433))
+* Refactor `bastardkb/tbkmini` ([#25438](https://github.com/qmk/qmk_firmware/pull/25438))
+* Convert `novelkeys/nk65` to use RGB Matrix ([#25450](https://github.com/qmk/qmk_firmware/pull/25450))
+* Convert moon to lite custom matrix ([#25452](https://github.com/qmk/qmk_firmware/pull/25452))
+* Refactor `bastardkb/skeletyl` ([#25456](https://github.com/qmk/qmk_firmware/pull/25456))
+* Refactor `bastardkb/scylla` ([#25459](https://github.com/qmk/qmk_firmware/pull/25459))
+* Refactor `bastardkb/dilemma/3x5_2` ([#25462](https://github.com/qmk/qmk_firmware/pull/25462))
+* Migrate `usb.force_nkro` to `host.default.nkro` ([#25468](https://github.com/qmk/qmk_firmware/pull/25468))
+* Give mouse report to pointing_device_task_user first in ploopyco devices ([#25475](https://github.com/qmk/qmk_firmware/pull/25475))
+* Refactor `bastardkb/charybdis/3x5` ([#25488](https://github.com/qmk/qmk_firmware/pull/25488))
+* Refactor `bastardkb/charybdis/3x6` ([#25493](https://github.com/qmk/qmk_firmware/pull/25493))
+* Refactor `bastardkb/charybdis/4x6` ([#25494](https://github.com/qmk/qmk_firmware/pull/25494))
+* Rebrand For Ll3ma Keyboards ([#25498](https://github.com/qmk/qmk_firmware/pull/25498))
+* Remove some encoder resolution that duplicate defaults ([#25517](https://github.com/qmk/qmk_firmware/pull/25517))
+* Remove overriding of `DF()` within keyboards ([#25541](https://github.com/qmk/qmk_firmware/pull/25541))
+* Refactor inland/kb83 ([#25542](https://github.com/qmk/qmk_firmware/pull/25542))
+* Refactor `tweetydabird/lotus58` ([#25547](https://github.com/qmk/qmk_firmware/pull/25547))
+* Swap spleeb to default GENERIC_PROMICRO_RP2040 board files ([#25564](https://github.com/qmk/qmk_firmware/pull/25564))
+
+Keyboard fixes:
+* Fix `keebio/quefrency/rev1:default60` ([#25423](https://github.com/qmk/qmk_firmware/pull/25423))
+* Fixup `bastardkb/tbkmini` keymap's build target ([#25458](https://github.com/qmk/qmk_firmware/pull/25458))
+* Miscellaneous fixes for lint warnings ([#25469](https://github.com/qmk/qmk_firmware/pull/25469))
+* Fix pytest/has_community default keymap location ([#25471](https://github.com/qmk/qmk_firmware/pull/25471))
+* Fix serial speed DD configuration & migrate keyboards ([#25546](https://github.com/qmk/qmk_firmware/pull/25546))
+* Update rgb x coordinate of rightmost column ([#25556](https://github.com/qmk/qmk_firmware/pull/25556))
+
+Bugs:
+* Fix buggy switch statement in quantum.c ([#25322](https://github.com/qmk/qmk_firmware/pull/25322))
+* Compilation fixes for `-fno-common` ([#25436](https://github.com/qmk/qmk_firmware/pull/25436))
+* Only userspace should be searched for keyboard aliases when locating keymaps ([#25477](https://github.com/qmk/qmk_firmware/pull/25477))
+* Allow `qmk flash <filename>` to flash AT32 boards ([#25497](https://github.com/qmk/qmk_firmware/pull/25497))

docs/ChangeLog/20251130.md

@@ -0,0 +1,190 @@
+# QMK Breaking Changes - 2025 Nov 30 Changelog
+
+## Notable Features {#notable-features}
+
+### Speculative Hold option for mod-taps: hold mods instantly while unsettled [#25572](https://github.com/qmk/qmk_firmware/pull/25572)
+
+Speculative Hold makes mod-tap keys more responsive by applying the modifier instantly on keydown, before the tap-hold decision is made. This is especially useful for actions like Shift+click and Ctrl+scroll wheel with an external mouse, which can feel laggy with standard mod-taps.
+
+The firmware holds the modifier speculatively. Once the key's behavior is settled:
+
+* If held, the modifier remains active as expected until the key is released.
+* If tapped, the speculative modifier is canceled just before the tapping keycode is sent.
+
+Speculative Hold applies the modifier early but does not change the underlying tap-hold decision logic. Speculative Hold is compatible to use in combination with any other tap-hold options.
+
+see the [Speculative Hold](../tap_hold#speculative-hold) documentation for more information.
+
+## Changes Requiring User Action
+
+### Updated Keyboard Codebases
+
+| Old Keyboard Name                | New Keyboard Name       |
+|----------------------------------|-------------------------|
+| 0xcb/splaytoraid/32u4            | 0xcb/splaytoraid        |
+| 0xcb/splaytoraid/rp2040_ce       | 0xcb/splaytoraid        |
+| 1upkeyboards/sweet16v2/kb2040    | 1upkeyboards/sweet16v2  |
+| 1upkeyboards/sweet16v2/pro_micro | 1upkeyboards/sweet16v2  |
+| 40percentclub/gherkin/kb2040     | 40percentclub/gherkin   |
+| 40percentclub/gherkin/pro_micro  | 40percentclub/gherkin   |
+| durgod/dgk6x/venus               | durgod/dgk6x/venus_ansi |
+
+### Reduce tap dance memory usage, move state out of data [#25415](https://github.com/qmk/qmk_firmware/pull/25415)
+
+The tap dance state has been separated from the action structure. Custom tap dance functions now receive the state as a separate parameter instead of accessing it through `action->state`.
+
+If your keymap uses custom tap dance functions that access the tap dance state, you need to update your code.
+
+* You can't use `action->state`. Instead you need to call `tap_dance_state_t *tap_dance_get_state(uint8_t tap_dance_idx)` to get the state.
+* You now get a pointer to the state, so use `->` notation rather than `.` notation to get fields from it.
+
+### Before:
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    tap_dance_action_t *action;
+
+    switch (keycode) {
+        case TD(CT_CLN):
+            action = tap_dance_get(QK_TAP_DANCE_GET_INDEX(keycode));
+            if (!record->event.pressed && action->state.count && !action->state.finished) {
+                tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data;
+                tap_code16(tap_hold->tap);
+            }
+
+    }
+    return true;
+}
+```
+### After:
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    tap_dance_action_t *action;
+    tap_dance_state_t* state;
+    switch (keycode) {
+        case TD(CT_CLN):
+            action = tap_dance_get(QK_TAP_DANCE_GET_INDEX(keycode));
+            state = tap_dance_get_state(QK_TAP_DANCE_GET_INDEX(keycode));
+            if (!record->event.pressed && state != NULL && state->count && !state->finished) {
+                tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data;
+                tap_code16(tap_hold->tap);
+            }
+    }
+    return true;
+}
+```
+
+## Deprecation Notices
+
+In line with the [notice period](../support_deprecation_policy#how-much-advance-notice-will-be-given), deprecation notices for larger items are listed here.
+
+### Remove override of QK_{LED,RGB}_MATRIX_TOGGLE keycode [#25672](https://github.com/qmk/qmk_firmware/pull/25672)
+
+[#24649](https://github.com/qmk/qmk_firmware/pull/24649) implemented genetic behavior, including keycodes, to cycle flags.
+
+Any overriding of existing keycodes that duplicate this behavior will be removed to ensure consistency with core functionality.
+
+## Full changelist
+
+Core:
+* suspend: suppress wake up keypress ([#23389](https://github.com/qmk/qmk_firmware/pull/23389))
+* [Feature Improvement]add option to keep layer state when recording dynamic macros ([#24418](https://github.com/qmk/qmk_firmware/pull/24418))
+* Add generic handling to cycle LED/RGB Matrix flags ([#24649](https://github.com/qmk/qmk_firmware/pull/24649))
+* Implement `mod_t` packed struct ([#25168](https://github.com/qmk/qmk_firmware/pull/25168))
+* Implement minimal connection update logic ([#25334](https://github.com/qmk/qmk_firmware/pull/25334))
+* Reduce tap dance memory usage, move state out of data ([#25415](https://github.com/qmk/qmk_firmware/pull/25415))
+* Refactor debounce algorithm with static allocation ([#25515](https://github.com/qmk/qmk_firmware/pull/25515))
+* Restructure Pixel Rain interval code ([#25516](https://github.com/qmk/qmk_firmware/pull/25516))
+* Guard remapping logic with MAGIC_ENABLE ([#25537](https://github.com/qmk/qmk_firmware/pull/25537))
+* Update default OLED font ([#25565](https://github.com/qmk/qmk_firmware/pull/25565))
+* Speculative Hold option for mod-taps: hold mods instantly while unsettled. ([#25572](https://github.com/qmk/qmk_firmware/pull/25572))
+* Simplify hue calculation in raindrops animation ([#25587](https://github.com/qmk/qmk_firmware/pull/25587))
+* Simplify tap_code16_delay ([#25595](https://github.com/qmk/qmk_firmware/pull/25595))
+* Debounce: Deprecate num_rows parameter ([#25632](https://github.com/qmk/qmk_firmware/pull/25632))
+* Add I2C Transmit and Receive function ([#25637](https://github.com/qmk/qmk_firmware/pull/25637))
+* [QP] Minor cleanup and support for RGB888 surface ([#25706](https://github.com/qmk/qmk_firmware/pull/25706))
+* Restrict mouse timer activation to movement keycodes ([#25716](https://github.com/qmk/qmk_firmware/pull/25716))
+* Update STM32F446 default HSE to 8MHz ([#25717](https://github.com/qmk/qmk_firmware/pull/25717))
+* making flowtap timer public so it can be used easily with combos ([#25731](https://github.com/qmk/qmk_firmware/pull/25731))
+* Add PixArt PAW-3222 mouse sensor driver ([#25763](https://github.com/qmk/qmk_firmware/pull/25763))
+* Merge upstream uf2conv changes ([#25786](https://github.com/qmk/qmk_firmware/pull/25786))
+* Partially skip generating community modules when none enabled ([#25819](https://github.com/qmk/qmk_firmware/pull/25819))
+
+CLI:
+* Generate default encoder resolution for sparse config ([#25247](https://github.com/qmk/qmk_firmware/pull/25247))
+* Add DIP Switch map support to keymap.json ([#25431](https://github.com/qmk/qmk_firmware/pull/25431))
+* Add return code to `qmk userspace-doctor` ([#25775](https://github.com/qmk/qmk_firmware/pull/25775))
+* Better defaulting of `{RGB,LED}_MATRIX_DEFAULT_FLAGS` ([#25785](https://github.com/qmk/qmk_firmware/pull/25785))
+* add BCD versions of QMK Version ([#25804](https://github.com/qmk/qmk_firmware/pull/25804))
+* Lint error on missing keyboard readme ([#25814](https://github.com/qmk/qmk_firmware/pull/25814))
+
+Submodule updates:
+* Update ChibiOS-Contrib. ([#25751](https://github.com/qmk/qmk_firmware/pull/25751))
+
+Keyboards:
+* `atreus`: restore intended matrix implementations ([#24082](https://github.com/qmk/qmk_firmware/pull/24082))
+* add SteelSeries prime, a stripped down prime+ ([#24719](https://github.com/qmk/qmk_firmware/pull/24719))
+* Add new macropad Sharkropad ([#24961](https://github.com/qmk/qmk_firmware/pull/24961))
+* Addition of the D60B tsangan pcb ([#25245](https://github.com/qmk/qmk_firmware/pull/25245))
+* Migrate `eeconfig_init_kb` implementations to config ([#25422](https://github.com/qmk/qmk_firmware/pull/25422))
+* Generate `CUSTOM_MATRIX = lite` without `matrix_pins.custom` ([#25453](https://github.com/qmk/qmk_firmware/pull/25453))
+* Add classic48 keyboard ([#25492](https://github.com/qmk/qmk_firmware/pull/25492))
+* add durgod venus iso support ([#25526](https://github.com/qmk/qmk_firmware/pull/25526))
+* Migrate `g_led_config` to DD (0-9, A) ([#25558](https://github.com/qmk/qmk_firmware/pull/25558))
+* Migrate `g_led_config` to DD (B, C) ([#25559](https://github.com/qmk/qmk_firmware/pull/25559))
+* Migrate `g_led_config` to DD (D) ([#25560](https://github.com/qmk/qmk_firmware/pull/25560))
+* Migrate `g_led_config` to DD (E, F) ([#25561](https://github.com/qmk/qmk_firmware/pull/25561))
+* Remove duplication of RP2040 config defaults ([#25563](https://github.com/qmk/qmk_firmware/pull/25563))
+* Refactor 40percentclub/ut47 ([#25571](https://github.com/qmk/qmk_firmware/pull/25571))
+* E7-V2 Implementation ([#25594](https://github.com/qmk/qmk_firmware/pull/25594))
+* Migrate `g_led_config` to DD (G) ([#25598](https://github.com/qmk/qmk_firmware/pull/25598))
+* Migrate `g_led_config` to DD (H) ([#25599](https://github.com/qmk/qmk_firmware/pull/25599))
+* Migrate `g_led_config` to DD (I) ([#25600](https://github.com/qmk/qmk_firmware/pull/25600))
+* Migrate `g_led_config` to DD (JK1) ([#25601](https://github.com/qmk/qmk_firmware/pull/25601))
+* Migrate `g_led_config` to DD (K2) ([#25602](https://github.com/qmk/qmk_firmware/pull/25602))
+* Migrate `g_led_config` to DD (K3) ([#25603](https://github.com/qmk/qmk_firmware/pull/25603))
+* Migrate `g_led_config` to DD (K4) ([#25605](https://github.com/qmk/qmk_firmware/pull/25605))
+* Migrate `g_led_config` to DD (K5) ([#25606](https://github.com/qmk/qmk_firmware/pull/25606))
+* Migrate `g_led_config` to DD (K6) ([#25607](https://github.com/qmk/qmk_firmware/pull/25607))
+* Refactor `40percentclub/gherkin` ([#25608](https://github.com/qmk/qmk_firmware/pull/25608))
+* Refactor `0xcb/splaytoraid` ([#25609](https://github.com/qmk/qmk_firmware/pull/25609))
+* Refactor `1upkeyboards/sweet16v2` ([#25610](https://github.com/qmk/qmk_firmware/pull/25610))
+* Migrate `g_led_config` to DD (K7) ([#25616](https://github.com/qmk/qmk_firmware/pull/25616))
+* Migrate `g_led_config` to DD (L) ([#25617](https://github.com/qmk/qmk_firmware/pull/25617))
+* Migrate `g_led_config` to DD (M1) ([#25618](https://github.com/qmk/qmk_firmware/pull/25618))
+* Migrate `g_led_config` to DD (M2) ([#25619](https://github.com/qmk/qmk_firmware/pull/25619))
+* Migrate `g_led_config` to DD (M3) ([#25620](https://github.com/qmk/qmk_firmware/pull/25620))
+* Migrate `g_led_config` to DD (NO) ([#25621](https://github.com/qmk/qmk_firmware/pull/25621))
+* Migrate `g_led_config` to DD (P) ([#25622](https://github.com/qmk/qmk_firmware/pull/25622))
+* Migrate `g_led_config` to DD (QR) ([#25623](https://github.com/qmk/qmk_firmware/pull/25623))
+* Migrate `g_led_config` to DD (S) ([#25624](https://github.com/qmk/qmk_firmware/pull/25624))
+* Migrate `g_led_config` to DD (TUW) ([#25625](https://github.com/qmk/qmk_firmware/pull/25625))
+* Remove idobao *_DISABLE_UNDERGLOW behaviour ([#25638](https://github.com/qmk/qmk_firmware/pull/25638))
+* Migrate `g_led_config` to DD (YZ) ([#25650](https://github.com/qmk/qmk_firmware/pull/25650))
+* Tidy Keebio keyboards ([#25653](https://github.com/qmk/qmk_firmware/pull/25653))
+* Remove encoder resolution where duplicating defaults ([#25654](https://github.com/qmk/qmk_firmware/pull/25654))
+* Custom oled fonts cleanup ([#25665](https://github.com/qmk/qmk_firmware/pull/25665))
+* Binepad KnobX1 - refactor `x1_layer_led` function as weak ([#25668](https://github.com/qmk/qmk_firmware/pull/25668))
+* Add DD {LED,RGB}_MATRIX_DEFAULT_FLAGS support ([#25671](https://github.com/qmk/qmk_firmware/pull/25671))
+* keyboards: Add Royal Kludge RK61 ([#25694](https://github.com/qmk/qmk_firmware/pull/25694))
+* Add TRKeyboard TRK2 keyboard ([#25754](https://github.com/qmk/qmk_firmware/pull/25754))
+
+Keyboard fixes:
+* Fixup `kprepublic/bm60hsrgb/rev2` ([#25644](https://github.com/qmk/qmk_firmware/pull/25644))
+* Fixup `kprepublic/bm60hsrgb_iso/rev2` ([#25648](https://github.com/qmk/qmk_firmware/pull/25648))
+* Fixup `kprepublic/bm60hsrgb_poker/rev2` ([#25649](https://github.com/qmk/qmk_firmware/pull/25649))
+* Fixup `rgbkb/pan` ([#25678](https://github.com/qmk/qmk_firmware/pull/25678))
+* Align use of keymap level `_kb` callbacks ([#25774](https://github.com/qmk/qmk_firmware/pull/25774))
+
+Others:
+* Rework converter docs ([#18314](https://github.com/qmk/qmk_firmware/pull/18314))
+* Update USBaspLoader ISP instructions ([#25590](https://github.com/qmk/qmk_firmware/pull/25590))
+* Add LED/RGB Matrix flags API docs ([#25673](https://github.com/qmk/qmk_firmware/pull/25673))
+
+Bugs:
+* Fix single key combos activating only once ([#25198](https://github.com/qmk/qmk_firmware/pull/25198))
+* Fix RGB matrix not syncing and turning off properly on timeout ([#25467](https://github.com/qmk/qmk_firmware/pull/25467))
+* Fix drv haptics docs by using the correct function name ([#25733](https://github.com/qmk/qmk_firmware/pull/25733))
+* Fix Magic GUI masking logic ([#25780](https://github.com/qmk/qmk_firmware/pull/25780))
+* Fix Speculative Hold to enable also right-handed RSFT, RCTL by default. ([#25797](https://github.com/qmk/qmk_firmware/pull/25797))
+* Fix community layout keymap discovery ([#25802](https://github.com/qmk/qmk_firmware/pull/25802))
+* Fix preference of output file for 'qmk generate-autocorrect-data' ([#25818](https://github.com/qmk/qmk_firmware/pull/25818))

docs/_sidebar.json

@@ -21,8 +21,14 @@
             { "text": "Debugging QMK", "link": "/faq_debug" },
             { "text": "Keymap FAQ", "link": "/faq_keymap" },
             { "text": "Squeezing Space from AVR", "link": "/squeezing_avr" },
-            { "text": "Glossary", "link": "/reference_glossary" },
+            { "text": "Glossary", "link": "/reference_glossary" }
-            { "text": "License Violations", "link": "/license_violations" }
+        ]
+    },
+    {
+        "text": "Licensing",
+        "items": [
+            { "text": "License Violations", "link": "/license_violations" },
+            { "text": "Proprietary Libraries", "link": "/proprietary_libs" }
         ]
     },
     {
@@ -169,6 +175,7 @@
                         ]
                     },
                     { "text": "Audio", "link": "/features/audio" },
+                    { "text": "Battery", "link": "/features/battery" },
                     { "text": "Bootmagic", "link": "/features/bootmagic" },
                     { "text": "Converters", "link": "/feature_converters" },
                     { "text": "Custom Matrix", "link": "/custom_matrix" },
@@ -207,7 +214,7 @@
                     { "text": "My Pull Request Was Flagged", "link": "/breaking_changes_instructions" },
                     {
                         "text": "Most Recent ChangeLog",
-                        "link": "/ChangeLog/20250525"
+                        "link": "/ChangeLog/20251130"
                     },
                     { "text": "Past Breaking Changes", "link": "/breaking_changes_history" },
                     { "text": "Deprecation Policy", "link": "/support_deprecation_policy" }

docs/breaking_changes.md

@@ -10,25 +10,25 @@ Practically, this means QMK merges the `develop` branch into the `master` branch
 
 ## What has been included in past Breaking Changes?
 
+* [2025 Nov 30](ChangeLog/20251130)
+* [2025 Aug 31](ChangeLog/20250831)
 * [2025 May 25](ChangeLog/20250525)
-* [2025 Feb 23](ChangeLog/20250223)
-* [2024 Nov 24](ChangeLog/20241124)
 * [Older Breaking Changes](breaking_changes_history)
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for Aug 31, 2025.
+The next Breaking Change is scheduled for February 22, 2026.
 
 ### Important Dates
 
-* 2025 May 25 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
+* 2025 Nov 30 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
-* 2025 Aug 3 - `develop` closed to new PRs.
+* 2026 Jan 25 - `develop` closed to new PRs.
-* 2025 Aug 3 - Call for testers.
+* 2026 Jan 25 - Call for testers.
-* 2025 Aug 17 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
+* 2026 Feb 8 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
-* 2025 Aug 24 - `develop` is locked, only critical bugfix PRs merged.
+* 2026 Feb 15 - `develop` is locked, only critical bugfix PRs merged.
-* 2025 Aug 29 - `master` is locked, no PRs merged.
+* 2026 Feb 20 - `master` is locked, no PRs merged.
-* 2025 Aug 31 - Merge `develop` to `master`.
+* 2026 Feb 22 - Merge `develop` to `master`.
-* 2025 Aug 31 - `master` is unlocked. PRs can be merged again.
+* 2026 Feb 22 - `master` is unlocked. PRs can be merged again.
 
 ## What changes will be included?
 

docs/breaking_changes_history.md

@@ -2,6 +2,8 @@
 
 This page links to all previous changelogs from the QMK Breaking Changes process.
 
+* [2025 Nov 30](ChangeLog/20251130) - version 0.31.0
+* [2025 Aug 31](ChangeLog/20250831) - version 0.30.0
 * [2025 May 25](ChangeLog/20250525) - version 0.29.0
 * [2025 Feb 23](ChangeLog/20250223) - version 0.28.0
 * [2024 Nov 24](ChangeLog/20241124) - version 0.27.0

docs/cli_commands.md

@@ -17,12 +17,12 @@ qmk compile [-c] <configuratorExport.json>
 **Usage for Keymaps**:
 
 ```
-qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] [--compiledb] -kb <keyboard_name> -km <keymap_name>
+qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] [--compiledb] -kb <keyboard> -km <keymap>
 ```
 
 **Usage in Keyboard Directory**:
 
-Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>`
+Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap>`
 ```
 qmk compile
 ```
@@ -30,7 +30,7 @@ qmk compile
 **Usage for building all keyboards that support a specific keymap**:
 
 ```
-qmk compile -kb all -km <keymap_name>
+qmk compile -kb all -km <keymap>
 ```
 
 **Example**:
@@ -62,7 +62,7 @@ $ qmk compile
 
 Must be under `qmk_firmware/layouts/`, and in a keymap folder.
 ```
-qmk compile -kb <keyboard_name>
+qmk compile -kb <keyboard>
 ```
 
 **Example**:
@@ -77,11 +77,11 @@ $ qmk compile -kb dz60
 
 It is possible to speed up compilation by adding the `-j`/`--parallel` flag.
 ```
-qmk compile -j <num_jobs> -kb <keyboard_name>
+qmk compile -j <num_jobs> -kb <keyboard>
 ```
 The `num_jobs` argument determines the maximum number of jobs that can be used. Setting it to zero will enable parallel compilation without limiting the maximum number of jobs.
 ```
-qmk compile -j 0 -kb <keyboard_name>
+qmk compile -j 0 -kb <keyboard>
 ```
 
 **Compilation Database**:
@@ -120,7 +120,7 @@ qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configurat
 **Usage for Keymaps**:
 
 ```
-qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>]
+qmk flash -kb <keyboard> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>]
 ```
 
 **Usage for pre-compiled firmwares**:
@@ -631,14 +631,15 @@ This command compiles all the External Userspace build targets.
 **Usage**:
 
 ```
-qmk userspace-compile [-h] [-e ENV] [-n] [-c] [-j PARALLEL] [-t]
+qmk userspace-compile [-h] [-e ENV] [-p] [-n] [-c] [-j PARALLEL] [-t]
 
 options:
   -h, --help            show this help message and exit
-  -e ENV, --env ENV     Set a variable to be passed to make. May be passed multiple times.
+  -e, --env ENV         Set a variable to be passed to make. May be passed multiple times.
+  -p, --print-failures  Print failed builds.
   -n, --dry-run         Don't actually build, just show the commands to be run.
   -c, --clean           Remove object files before compiling.
-  -j PARALLEL, --parallel PARALLEL
+  -j, --parallel PARALLEL
                         Set the number of parallel make jobs; 0 means unlimited.
   -t, --no-temp         Remove temporary files during build.
 ```

docs/config_options.md

@@ -364,8 +364,6 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
 
 ## Build Options
 
-* `DEFAULT_FOLDER`
-  * Used to specify a default folder when a keyboard has more than one sub-folder.
 * `FIRMWARE_FORMAT`
   * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
 * `SRC`

docs/custom_matrix.md

@@ -74,7 +74,7 @@ void matrix_init(void) {
     // TODO: initialize hardware and global matrix state here
 
     // Unless hardware debouncing - Init the configured debounce routine
-    debounce_init(MATRIX_ROWS);
+    debounce_init();
 
     // This *must* be called for correct keyboard behavior
     matrix_init_kb();
@@ -86,7 +86,7 @@ uint8_t matrix_scan(void) {
     // TODO: add matrix scanning routine here
 
     // Unless hardware debouncing - use the configured debounce routine
-    changed = debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+    changed = debounce(raw_matrix, matrix, changed);
 
     // This *must* be called for correct keyboard behavior
     matrix_scan_kb();

docs/custom_quantum_functions.md

@@ -145,7 +145,7 @@ void keyboard_pre_init_user(void) {
 
 This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized.
 
-This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started.
+This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependent on where it's started.
 
 
 ### `matrix_init_*` Function Documentation
@@ -209,7 +209,7 @@ You should use this function if you need custom matrix scanning code. It can als
 
 This function gets called at the end of all QMK processing, before starting the next iteration. You can safely assume that QMK has dealt with the last matrix scan at the time that these functions are invoked -- layer states have been updated, USB reports have been sent, LEDs have been updated, and displays have been drawn.
 
-Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throtting their behaviour if you do indeed require implementing something special.
+Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throttling their behaviour if you do indeed require implementing something special.
 
 ### Example `void housekeeping_task_user(void)` implementation
 
@@ -246,7 +246,7 @@ void check_rgb_timeout(void) {
     }
 }
 /* Then, call the above functions from QMK's built in post processing functions like so */
-/* Runs at the end of each scan loop, check if RGB timeout has occured or not */
+/* Runs at the end of each scan loop, check if RGB timeout has occurred or not */
 void housekeeping_task_user(void) {
 #ifdef RGBLIGHT_TIMEOUT
     check_rgb_timeout();

docs/data_driven_config.md

@@ -6,7 +6,7 @@ This page describes how QMK's data driven JSON configuration system works. It is
 
 Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 4000 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand.
 
-We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use.
+We have also been working on bringing the power of QMK to people who aren't comfortable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use.
 
 Now we have support for generating `rules.mk` and `config.h` values from `info.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work.
 

docs/driver_installation_zadig.md

@@ -4,7 +4,7 @@ QMK presents itself to the host as a regular HID keyboard device, and as such re
 
 There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the HalfKay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver.
 
-We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the `qmk_install.sh` script will have already installed the drivers for you.
+We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the QMK CLI installation script will have already installed the drivers for you.
 
 ## Installation
 
@@ -22,7 +22,7 @@ If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is pr
 
 If the arrow appears green, select the driver, and click **Install Driver**. See the [list of known bootloaders](#list-of-known-bootloaders) for the correct driver to install.
 
-![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png)
+![Zadig with a bootloader driver correctly installed](/b8VgXzx.png)
 
 Finally, unplug and replug the keyboard to make sure the new driver has been loaded. If you are using the QMK Toolbox to flash, exit and restart it too, as it can sometimes fail to recognize the driver change.
 
@@ -30,15 +30,15 @@ Finally, unplug and replug the keyboard to make sure the new driver has been loa
 
 If you find that you can no longer type with the keyboard, you may have accidentally replaced the driver for the keyboard itself instead of for the bootloader. This can happen when the keyboard is not in the bootloader mode. You can easily confirm this in Zadig - a healthy keyboard has the `HidUsb` driver installed on all of its interfaces:
 
-![A healthy keyboard as seen by Zadig](https://i.imgur.com/Hx0E5kC.png)
+![A healthy keyboard as seen by Zadig](/Hx0E5kC.png)
 
 Open the Device Manager, select **View → Devices by container**, and look for an entry with your keyboard's name.
 
-![The board with the wrong driver installed, in Device Manager](https://i.imgur.com/o7WLvBl.png)
+![The board with the wrong driver installed, in Device Manager](/o7WLvBl.png)
 
 Right-click each entry and hit **Uninstall device**. Make sure to tick **Delete the driver software for this device** first if it appears.
 
-![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png)
+![The Device Uninstall dialog, with the "delete driver" checkbox ticked](/aEs2RuA.png)
 
 Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! Otherwise, repeat this process until Zadig reports the correct driver.
 
@@ -54,11 +54,11 @@ Open the Device Manager, select **View → Devices by container**, and look for
 
 Find the `Inf name` value in the Details tab of the device properties. This should generally be something like `oemXX.inf`:
 
-![Device properties showing the Inf name value](https://i.imgur.com/Bu4mk9m.png)
+![Device properties showing the Inf name value](/Bu4mk9m.png)
 
 Then, open a new Command Prompt window as an Administrator (type in `cmd` into the Start menu and press Ctrl+Shift+Enter). Run `pnputil /enum-drivers` to verify the `Inf name` matches the `Published Name` field of one of the entries:
 
-![pnputil output with matching driver highlighted](https://i.imgur.com/3RrSjzW.png)
+![pnputil output with matching driver highlighted](/3RrSjzW.png)
 
 Run `pnputil /delete-driver oemXX.inf /uninstall`. This will delete the driver and remove it from any devices using it. Note that this will not uninstall the device itself.
 

docs/drivers/aw20216s.md

@@ -44,7 +44,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = {

docs/drivers/battery.md

@@ -1,6 +1,6 @@
 # Battery Driver
 
-This driver provides support for sampling battery level.
+This driver provides support for directly sampling battery level.
 
 ## Usage
 
@@ -10,21 +10,17 @@ To use this driver, add the following to your `rules.mk`:
 BATTERY_DRIVER_REQUIRED = yes
 ```
 
-## Basic Configuration {#basic-configuration}
+::::info Note
-
+This is already configured for you if you are using the [Battery](../features/battery) feature.
-Add the following to your `config.h`:
+::::
-
-|Define                    |Default |Description                                       |
-|--------------------------|--------|--------------------------------------------------|
-|`BATTERY_SAMPLE_INTERVAL` |`30000` |The time between battery samples in milliseconds. |
 
 ## Driver Configuration {#driver-configuration}
 
-Driver selection can be configured in `rules.mk` as `BATTERY_DRIVER`. Valid values are `adc` (default), `vendor`, or `custom`. See below for information on individual drivers.
+Driver selection can be configured in `rules.mk` as `BATTERY_DRIVER`. Valid values are `adc`, `vendor`, or `custom`. See below for information on individual drivers.
 
 ### ADC Driver {#adc-driver}
 
-This is the default battery driver. The default configuration assumes the battery is connected to a ADC capable pin through a voltage divider.
+The default configuration assumes the battery is connected to a ADC capable pin through a voltage divider.
 
 ```make
 BATTERY_DRIVER = adc
@@ -32,42 +28,25 @@ BATTERY_DRIVER = adc
 
 The following `#define`s apply only to the `adc` driver:
 
-|Define                       |Default       |Description                                                   |
+|Define                           |Default       |Description                                                   |
-|-----------------------------|--------------|--------------------------------------------------------------|
+|---------------------------------|--------------|--------------------------------------------------------------|
-|`BATTERY_PIN`                |*Not defined* |The GPIO pin connected to the voltage divider.                |
+|`BATTERY_ADC_PIN`                |*Not defined* |The GPIO pin connected to the voltage divider.                |
-|`BATTERY_REF_VOLTAGE_MV`     |`3300`        |The ADC reverence voltage, in millivolts.                     |
+|`BATTERY_ADC_REF_VOLTAGE_MV`     |`3300`        |The ADC reverence voltage, in millivolts.                     |
-|`BATTERY_VOLTAGE_DIVIDER_R1` |`100`         |The voltage divider resistance, in kOhm. Set to 0 to disable. |
+|`BATTERY_ADC_VOLTAGE_DIVIDER_R1` |`100`         |The voltage divider resistance, in kOhm. Set to 0 to disable. |
-|`BATTERY_VOLTAGE_DIVIDER_R2` |`100`         |The voltage divider resistance, in kOhm. Set to 0 to disable. |
+|`BATTERY_ADC_VOLTAGE_DIVIDER_R2` |`100`         |The voltage divider resistance, in kOhm. Set to 0 to disable. |
-|`BATTERY_ADC_RESOLUTION`     |`10`          |The ADC resolution configured for the ADC Driver.             |
+|`BATTERY_ADC_RESOLUTION`         |`10`          |The ADC resolution configured for the ADC Driver.             |
 
-## Functions
+### Custom Driver {#custom-driver}
 
-### `uint8_t battery_get_percent(void)` {#api-battery-get-percent}
+A custom driver is expected to implement the following interface:
 
-Sample battery level.
+```c
+void battery_driver_init(void) {
+    // Perform any initialisation here
+}
 
-#### Return Value {#api-battery-get-percent-return}
+uint8_t battery_driver_sample_percent(void) {
-
+    // Read and return current state here
-The battery percentage, in the range 0-100.
+    return value;
-
+}
-## Callbacks
+```
-
-### `void battery_percent_changed_user(uint8_t level)` {#api-battery-percent-changed-user}
-
-User hook called when battery level changed.
-
-### Arguments {#api-battery-percent-changed-user-arguments}
-
- - `uint8_t level`  
-   The battery percentage, in the range 0-100.
-
----
-
-### `void battery_percent_changed_kb(uint8_t level)` {#api-battery-percent-changed-kb}
-
-Keyboard hook called when battery level changed.
-
-### Arguments {#api-battery-percent-changed-kb-arguments}
-
- - `uint8_t level`  
-   The battery percentage, in the range 0-100.

docs/drivers/i2c.md

@@ -221,6 +221,31 @@ Receive multiple bytes from the selected I2C device.
 
 ---
 
+### `i2c_status_t i2c_transmit_and_receive(uint8_t address, const uint8_t* tx_data, uint16_t tx_length, uint8_t* rx_data, uint16_t rx_length, uint16_t timeout)` {#api-i2c-transmit-and-receive}
+
+Send and receive multiple bytes from the selected I2C device.
+
+#### Arguments {#api-i2c-transmit-and-receive-arguments}
+
+ - `uint8_t address`
+   The 7-bit I2C address of the device.
+ - `const uint8_t* tx_data`
+   A pointer to the data to transmit.
+ - `uint16_t tx_length`
+   The number of bytes to write. Take care not to overrun the length of `tx_data`.
+ - `uint8_t* rx_data`
+   A pointer to a buffer to read into.
+ - `uint16_t rx_length`
+   The number of bytes to read. Take care not to overrun the length of `data`.
+ - `uint16_t timeout`
+   The time in milliseconds to wait for a response from the target device.
+
+#### Return Value {#api-i2c-transmit-and-receive-return}
+
+`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+
+---
+
 ### `i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-write-register}
 
 Write to a register with an 8-bit address on the I2C device.

docs/drivers/is31fl3218.md

@@ -37,7 +37,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = {

docs/drivers/is31fl3236.md

@@ -50,7 +50,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = {

docs/drivers/is31fl3729.md

@@ -120,7 +120,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3729_led_t PROGMEM g_is31fl3729_leds[IS31FL3729_LED_COUNT] = {

docs/drivers/is31fl3731.md

@@ -61,7 +61,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = {

docs/drivers/is31fl3733.md

@@ -145,7 +145,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = {

docs/drivers/is31fl3736.md

@@ -129,7 +129,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = {

docs/drivers/is31fl3737.md

@@ -117,7 +117,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = {

docs/drivers/is31fl3741.md

@@ -117,7 +117,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3741_led_t PROGMEM g_is31fl3741_leds[IS31FL3741_LED_COUNT] = {

docs/drivers/is31fl3742a.md

@@ -117,7 +117,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3742a_led_t PROGMEM g_is31fl3742a_leds[IS31FL3742A_LED_COUNT] = {

docs/drivers/is31fl3743a.md

@@ -127,7 +127,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3743a_led_t PROGMEM g_is31fl3743a_leds[IS31FL3743A_LED_COUNT] = {

docs/drivers/is31fl3745.md

@@ -127,7 +127,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3745_led_t PROGMEM g_is31fl3745_leds[IS31FL3745_LED_COUNT] = {

docs/drivers/is31fl3746a.md

@@ -132,7 +132,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const is31fl3746a_led_t PROGMEM g_is31fl3746a_leds[IS31FL3746A_LED_COUNT] = {

docs/drivers/serial.md

@@ -63,7 +63,7 @@ SERIAL_DRIVER = bitbang
 
 ## USART Half-duplex
 
-Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or imcompatible PCB design).
+Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or incompatible PCB design).
 
 ### Pin configuration
 
@@ -307,7 +307,7 @@ This is the default time window in milliseconds in which a successful communicat
 
 ## Troubleshooting
 
-If you're having issues withe serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file:
+If you're having issues with serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file:
 
 ```c
 #define SERIAL_DEBUG

docs/drivers/snled27351.md

@@ -52,7 +52,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config
 
 ## LED Mapping {#led-mapping}
 
-In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`:
+In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
 
 ```c
 const snled27351_led_t PROGMEM g_snled27351_leds[SNLED27351_LED_COUNT] = {

docs/drivers/ws2812.md

@@ -144,18 +144,30 @@ The following defines apply only to ARM devices:
 |`WS2812_T1L`|`(WS2812_TIMING - WS2812_T1H)`|The length of a "1" bit's low phase in nanoseconds (bitbang and PIO drivers only)|
 |`WS2812_T0L`|`(WS2812_TIMING - WS2812_T0H)`|The length of a "0" bit's low phase in nanoseconds (bitbang and PIO drivers only)|
 
-### Push-Pull and Open Drain {#push-pull-open-drain}
+### Logic Levels {#logic-levels}
 
-By default, the GPIO used for data transmission is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground.
+WS2812 LEDs usually operate at 5V, but some microcontrollers, particularly ARM-based ones, run on 3.3V. This can pose an issue when driving the LED chain as the logic level voltage is lower than the power supply voltage, leading to unreliable data transmission. There are two main workarounds:
 
-For situations where the logic level voltage is lower than the power supply voltage, however, this can pose an issue. The solution is to configure the pin for *open drain* mode instead, and use a pullup resistor between the DI pin and VCC. In this mode, the MCU can only pull the GPIO *low*, or leave it floating. The pullup resistor is then responsible for pulling the line high, when the MCU is not driving the GPIO.
+#### 1. Open Drain Circuit {#open-drain-circuit}
 
-To configure the DI pin for open drain configuration, add the following to your `config.h`:
+By default, `WS2812_DI_PIN` is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground; however, it can be configured in *open drain* mode instead.
+
+In this mode, the MCU will only pull the GPIO *low*, and leaves it floating otherwise. A pullup resistor (typically around 10kΩ) between DI and 5V is then responsible for pulling the line high when the MCU is not driving the GPIO.
+
+To use the DI pin in open drain configuration, add the following to your `config.h`:
 
 ```c
 #define WS2812_EXTERNAL_PULLUP
 ```
 
+::: warning
+Because the GPIO is being pulled to 5V in this situation rather than VCC (3.3V), **it must be a 5V tolerant pin**. Consult your MCU's datasheet first – if there are no eligible pins, you must use a level shifter instead.
+:::
+
+#### 2. Level Shifter {#level-shifter}
+
+A level shifter IC, such as the SN74LV1T34, can be placed between the GPIO and the first LED's DI pin to convert the 3.3V logic to 5V. This requires no additional configuration in the firmware, nor a 5V tolerant GPIO, but may be more expensive and is generally less handwire-friendly.
+
 ### SPI Driver {#arm-spi-driver}
 
 Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like:

docs/easy_maker.md

@@ -24,7 +24,7 @@ As its name implies Direct Pin works by connecting one switch per pin. The other
 
 Here is a schematic showing how we connect a single button to pin A3 on a ProMicro:
 
-![Schematic diagram showing a ProMicro with a wire coming out of A3, connecting to the left side of a switch. Another wire comes out of the right side of the switch to connect to the Ground Plane.](https://i.imgur.com/JcDhZll.png)
+![Schematic diagram showing a ProMicro with a wire coming out of A3, connecting to the left side of a switch. Another wire comes out of the right side of the switch to connect to the Ground Plane.](/JcDhZll.png)
 
 Once you have wired your switches you can assign keycodes to each pin and build a firmware by selecting the MCU you are using from the Keyboard dropdown. Use this link to show only Easy Maker Direct Pin:
 

docs/faq_build.md

@@ -44,7 +44,7 @@ Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices m
 
 Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader, or none at all.
 
-Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually.
+Re-running the QMK installation script (`curl -fsSL https://install.qmk.fm | sh`) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually.
 
 If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig) for more detailed information.
 

docs/faq_general.md

@@ -38,7 +38,7 @@ Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
 
 That's amazing! We would love to assist you with that!
 
-In fact, we have a [whole page](https://qmk.fm/powered/) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK.
+In fact, we have a [whole page](https://qmk.fm/trademark) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK.
 
 If you have any questions about this, open an issue or head to [Discord](https://discord.gg/qmk).
 

docs/faq_keymap.md

@@ -13,7 +13,7 @@ Keycodes are actually defined in [quantum/keycode.h](https://github.com/qmk/qmk_
 There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
 
 <!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
-![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
+![Keyboard Layout Image](/5wsh5wM.png)
 
 ## How Can I Make Custom Names For Complex Keycodes?
 

docs/feature_advanced_keycodes.md

@@ -2,36 +2,36 @@
 
 These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
 
-|Key       |Aliases                           |Description                                                                    |
+|Key       |Aliases                        |Description                                                                    |
-|----------|----------------------------------|-------------------------------------------------------------------------------|
+|----------|-------------------------------|-------------------------------------------------------------------------------|
-|`LCTL(kc)`|`C(kc)`                           |Hold Left Control and press `kc`                                               |
+|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                                               |
-|`LSFT(kc)`|`S(kc)`                           |Hold Left Shift and press `kc`                                                 |
+|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                                                 |
-|`LALT(kc)`|`A(kc)`, `LOPT(kc)`               |Hold Left Alt and press `kc`                                                   |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                                                   |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`   |Hold Left GUI and press `kc`                                                   |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                                                   |
-|`LCS(kc)` |                                  |Hold Left Control and Left Shift and press `kc`                                |
+|`LCS(kc)` |                               |Hold Left Control and Left Shift and press `kc`                                |
-|`LCA(kc)` |                                  |Hold Left Control and Left Alt and press `kc`                                  |
+|`LCA(kc)` |                               |Hold Left Control and Left Alt and press `kc`                                  |
-|`LCG(kc)` |                                  |Hold Left Control and Left GUI and press `kc`                                  |
+|`LCG(kc)` |                               |Hold Left Control and Left GUI and press `kc`                                  |
-|`LSA(kc)` |                                  |Hold Left Shift and Left Alt and press `kc`                                    |
+|`LSA(kc)` |                               |Hold Left Shift and Left Alt and press `kc`                                    |
-|`LSG(kc)` |`SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and Left GUI and press `kc`                                    |
+|`LSG(kc)` |                               |Hold Left Shift and Left GUI and press `kc`                                    |
-|`LAG(kc)` |                                  |Hold Left Alt and Left GUI and press `kc`                                      |
+|`LAG(kc)` |                               |Hold Left Alt and Left GUI and press `kc`                                      |
-|`LCSG(kc)`|                                  |Hold Left Control, Left Shift and Left GUI and press `kc`                      |
+|`LCSG(kc)`|                               |Hold Left Control, Left Shift and Left GUI and press `kc`                      |
-|`LCAG(kc)`|                                  |Hold Left Control, Left Alt and Left GUI and press `kc`                        |
+|`LCAG(kc)`|                               |Hold Left Control, Left Alt and Left GUI and press `kc`                        |
-|`LSAG(kc)`|                                  |Hold Left Shift, Left Alt and Left GUI and press `kc`                          |
+|`LSAG(kc)`|                               |Hold Left Shift, Left Alt and Left GUI and press `kc`                          |
-|`RCTL(kc)`|                                  |Hold Right Control and press `kc`                                              |
+|`RCTL(kc)`|                               |Hold Right Control and press `kc`                                              |
-|`RSFT(kc)`|                                  |Hold Right Shift and press `kc`                                                |
+|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                                                |
-|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`            |Hold Right Alt and press `kc`                                                  |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                                                  |
-|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)`            |Hold Right GUI and press `kc`                                                  |
+|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)`         |Hold Right GUI and press `kc`                                                  |
-|`RCA(kc)` |                                  |Hold Right Control and Right Alt and press `kc`                                |
+|`RCA(kc)` |                               |Hold Right Control and Right Alt and press `kc`                                |
-|`RCS(kc)` |                                  |Hold Right Control and Right Shift and press `kc`                              |
+|`RCS(kc)` |                               |Hold Right Control and Right Shift and press `kc`                              |
-|`RCG(kc)` |                                  |Hold Right Control and Right GUI and press `kc`                                |
+|`RCG(kc)` |                               |Hold Right Control and Right GUI and press `kc`                                |
-|`RSA(kc)` |`SAGR(kc)`                        |Hold Right Shift and Right Alt and press `kc`                                  |
+|`RSA(kc)` |                               |Hold Right Shift and Right Alt and press `kc`                                  |
-|`RSG(kc)` |                                  |Hold Right Shift and Right GUI and press `kc`                                  |
+|`RSG(kc)` |                               |Hold Right Shift and Right GUI and press `kc`                                  |
-|`RAG(kc)` |                                  |Hold Right Alt and Right GUI and press `kc`                                    |
+|`RAG(kc)` |                               |Hold Right Alt and Right GUI and press `kc`                                    |
-|`RCSG(kc)`|                                  |Hold Right Control, Right Shift and Right GUI and press `kc`                   |
+|`RCSG(kc)`|                               |Hold Right Control, Right Shift and Right GUI and press `kc`                   |
-|`RCAG(kc)`|                                  |Hold Right Control, Right Alt and Right GUI and press `kc`                     |
+|`RCAG(kc)`|                               |Hold Right Control, Right Alt and Right GUI and press `kc`                     |
-|`RSAG(kc)`|                                  |Hold Right Shift, Right Alt and Right GUI and press `kc`                       |
+|`RSAG(kc)`|                               |Hold Right Shift, Right Alt and Right GUI and press `kc`                       |
-|`MEH(kc)` |                                  |Hold Left Control, Left Shift and Left Alt and press `kc`                      |
+|`MEH(kc)` |                               |Hold Left Control, Left Shift and Left Alt and press `kc`                      |
-|`HYPR(kc)`|                                  |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`<sup>1</sup>|
+|`HYPR(kc)`|                               |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`<sup>1</sup>|
 
 <sup>1. More information on the Hyper key can be found on [this blog post by Brett Terpstra](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/).</sup>
 

docs/feature_converters.md

@@ -2,8 +2,22 @@
 
 This page documents the automated process for converting keyboards to use drop-in replacement controllers. This process is designed to be easy to use and can be completed in a few simple steps.
 
+You can generate the firmware by appending `-e CONVERT_TO=<target>` to your compile/flash command. For example:
+
+```sh
+qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c
+```
+
+You can also configure this within your [keymap](#keymap) to accomplish the same thing.
+
+::: tip
+If you get build errors, you will need to convert the keyboard's code to be [compatible](#keyboard-req) with the converter feature, or provide additional [keymap](#keymap-add) configuration.
+:::
+
 ## Supported Converters
 
+Each converter category is broken down by its declared `pin compatibility`. This ensures that only valid combinations are attempted.
+
 The following converters are available at this time:
 
 | From       | To                |
@@ -28,86 +42,56 @@ The following converters are available at this time:
 | `elite_c`  | `helios`          |
 | `elite_c`  | `liatris`         |
 
+## Configuration
 
-## Overview
+Configuring a converter to use can be done by adding one of the following lines to your keymaps's configuration:
 
-Each converter category is broken down by its declared `pin compatibility`. This ensures that only valid combinations are attempted. You can generate the firmware by appending `-e CONVERT_TO=<target>` to your compile/flash command. For example:
+:::::tabs
 
-```sh
+==== keymap.json
-qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c
+
+```json [keymap.json]
+{
+    "version": 1,
+    "keyboard": "keebio/bdn9/rev1",
+    "keymap": "keebio_bdn9_rev1_layout_2025-05-20",
+    "converter": "proton_c", // [!code focus]
+    "layout": "LAYOUT",
+}
 ```
 
-You can also add the same `CONVERT_TO=<target>` to your keymap's `rules.mk`, which will accomplish the same thing.
+==== rules.mk
-
-::: tip
-If you get errors about `PORTB/DDRB`, etc not being defined, you'll need to convert the keyboard's code to use the [GPIO Controls](drivers/gpio) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all.
-:::
-
-### Conditional Configuration
-
-Once a converter is enabled, it exposes the `CONVERT_TO_<target_uppercase>` flag that you can use in your code with `#ifdef`s, For example:
-
-```c
-#ifdef CONVERT_TO_PROTON_C
-    // Proton C code
-#else
-    // Pro Micro code
-#endif
-```
-
-### Pin Compatibility
-
-To ensure compatibility, provide validation, and enable future workflows, a keyboard should declare its `pin compatibility`. For legacy reasons, this is currently assumed to be `promicro`. The following pin compatibility interfaces are currently defined:
-
-| Pin Compatibility | Notes                             |
-|-------------------|-----------------------------------|
-| `promicro`        | Includes RX/TX LEDs               |
-| `elite_c`         | Includes bottom row pins, no LEDs |
-
-To declare the base for conversions, add this line to your keyboard's `rules.mk`:
 
 ```makefile
-PIN_COMPATIBLE = elite_c
+CONVERT_TO = proton_c
 ```
 
-## Pro Micro
+:::::
 
-If a board currently supported in QMK uses a [Pro Micro](https://www.sparkfun.com/products/12640) (or compatible board), the supported alternative controllers are:
+::: tip
+If you get build errors, you will need to convert the keyboard's code to be [compatible](#keyboard-req) with the converter feature, or provide additional [keymap](#keymap-add) configuration.
+:::
 
-| Device                                                                                   | Target            |
+## Pro Micro Converters
-|------------------------------------------------------------------------------------------|-------------------|
-| [Proton C](https://qmk.fm/proton-c/)                                                     | `proton_c`        |
-| [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040)                            | `kb2040`          |
-| [SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288)                   | `sparkfun_pm2040` |
-| [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622)                           | `blok`            |
-| [Bit-C PRO](https://nullbits.co/bit-c-pro)                                               | `bit_c_pro`       |
-| [STeMCell](https://github.com/megamind4089/STeMCell)                                     | `stemcell`        |
-| [customMK Bonsai C4](https://shop.custommk.com/products/bonsai-c4-microcontroller-board) | `bonsai_c4`       |
-| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040)         | `elite_pi`        |
-| [0xCB Helios](https://keeb.supply/products/0xcb-helios)                                  | `helios`          |
-| [Liatris](https://splitkb.com/products/liatris)                                          | `liatris`         |
-| [Imera](https://splitkb.com/products/imera)                                              | `imera`           |
-| [Michi](https://github.com/ci-bus/michi-promicro-rp2040)                                 | `michi`           |
-| [Svlinky](https://github.com/sadekbaroudi/svlinky)                                       | `svlinky`         |
 
-Converter summary:
+If a board currently supported by QMK uses a [Pro Micro](https://www.sparkfun.com/products/12640) (or compatible board), the supported alternative controllers are:
 
-| Target            | Argument                        | `rules.mk`                   | Condition                           |
+| Device                                                                                   | Target            | CLI Argument                    | `rules.mk`                   | Condition                           |
-|-------------------|---------------------------------|------------------------------|-------------------------------------|
+|------------------------------------------------------------------------------------------|-------------------|---------------------------------|------------------------------|-------------------------------------|
-| `proton_c`        | `-e CONVERT_TO=proton_c`        | `CONVERT_TO=proton_c`        | `#ifdef CONVERT_TO_PROTON_C`        |
+| [Proton C](https://qmk.fm/proton-c/)                                                     | `proton_c`        | `-e CONVERT_TO=proton_c`        | `CONVERT_TO=proton_c`        | `#ifdef CONVERT_TO_PROTON_C`        |
-| `kb2040`          | `-e CONVERT_TO=kb2040`          | `CONVERT_TO=kb2040`          | `#ifdef CONVERT_TO_KB2040`          |
+| [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040)                            | `kb2040`          | `-e CONVERT_TO=kb2040`          | `CONVERT_TO=kb2040`          | `#ifdef CONVERT_TO_KB2040`          |
-| `sparkfun_pm2040` | `-e CONVERT_TO=sparkfun_pm2040` | `CONVERT_TO=sparkfun_pm2040` | `#ifdef CONVERT_TO_SPARKFUN_PM2040` |
+| [SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288)                   | `sparkfun_pm2040` | `-e CONVERT_TO=sparkfun_pm2040` | `CONVERT_TO=sparkfun_pm2040` | `#ifdef CONVERT_TO_SPARKFUN_PM2040` |
-| `blok`            | `-e CONVERT_TO=blok`            | `CONVERT_TO=blok`            | `#ifdef CONVERT_TO_BLOK`            |
+| [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622)                           | `blok`            | `-e CONVERT_TO=blok`            | `CONVERT_TO=blok`            | `#ifdef CONVERT_TO_BLOK`            |
-| `bit_c_pro`       | `-e CONVERT_TO=bit_c_pro`       | `CONVERT_TO=bit_c_pro`       | `#ifdef CONVERT_TO_BIT_C_PRO`       |
+| [Bit-C PRO](https://nullbits.co/bit-c-pro)                                               | `bit_c_pro`       | `-e CONVERT_TO=bit_c_pro`       | `CONVERT_TO=bit_c_pro`       | `#ifdef CONVERT_TO_BIT_C_PRO`       |
-| `stemcell`        | `-e CONVERT_TO=stemcell`        | `CONVERT_TO=stemcell`        | `#ifdef CONVERT_TO_STEMCELL`        |
+| [STeMCell](https://github.com/megamind4089/STeMCell)                                     | `stemcell`        | `-e CONVERT_TO=stemcell`        | `CONVERT_TO=stemcell`        | `#ifdef CONVERT_TO_STEMCELL`        |
-| `bonsai_c4`       | `-e CONVERT_TO=bonsai_c4`       | `CONVERT_TO=bonsai_c4`       | `#ifdef CONVERT_TO_BONSAI_C4`       |
+| [customMK Bonsai C4](https://shop.custommk.com/products/bonsai-c4-microcontroller-board) | `bonsai_c4`       | `-e CONVERT_TO=bonsai_c4`       | `CONVERT_TO=bonsai_c4`       | `#ifdef CONVERT_TO_BONSAI_C4`       |
-| `rp2040_ce`       | `-e CONVERT_TO=rp2040_ce`       | `CONVERT_TO=rp2040_ce`       | `#ifdef CONVERT_TO_RP2040_CE`       |
+| [RP2040 Community Edition](#rp2040_ce)                                                   | `rp2040_ce`       | `-e CONVERT_TO=rp2040_ce`       | `CONVERT_TO=rp2040_ce`       | `#ifdef CONVERT_TO_RP2040_CE`       |
-| `elite_pi`        | `-e CONVERT_TO=elite_pi`        | `CONVERT_TO=elite_pi`        | `#ifdef CONVERT_TO_ELITE_PI`        |
+| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040)         | `elite_pi`        | `-e CONVERT_TO=elite_pi`        | `CONVERT_TO=elite_pi`        | `#ifdef CONVERT_TO_ELITE_PI`        |
-| `helios`          | `-e CONVERT_TO=helios`          | `CONVERT_TO=helios`          | `#ifdef CONVERT_TO_HELIOS`          |
+| [0xCB Helios](https://keeb.supply/products/0xcb-helios)                                  | `helios`          | `-e CONVERT_TO=helios`          | `CONVERT_TO=helios`          | `#ifdef CONVERT_TO_HELIOS`          |
-| `liatris`         | `-e CONVERT_TO=liatris`         | `CONVERT_TO=liatris`         | `#ifdef CONVERT_TO_LIATRIS`         |
+| [Liatris](https://splitkb.com/products/liatris)                                          | `liatris`         | `-e CONVERT_TO=liatris`         | `CONVERT_TO=liatris`         | `#ifdef CONVERT_TO_LIATRIS`         |
-| `imera`           | `-e CONVERT_TO=imera`           | `CONVERT_TO=imera`           | `#ifdef CONVERT_TO_IMERA`           |
+| [Imera](https://splitkb.com/products/imera)                                              | `imera`           | `-e CONVERT_TO=imera`           | `CONVERT_TO=imera`           | `#ifdef CONVERT_TO_IMERA`           |
-| `michi`           | `-e CONVERT_TO=michi`           | `CONVERT_TO=michi`           | `#ifdef CONVERT_TO_MICHI`           |
+| [Michi](https://github.com/ci-bus/michi-promicro-rp2040)                                 | `michi`           | `-e CONVERT_TO=michi`           | `CONVERT_TO=michi`           | `#ifdef CONVERT_TO_MICHI`           |
-| `svlinky`         | `-e CONVERT_TO=svlinky`         | `CONVERT_TO=svlinky`         | `#ifdef CONVERT_TO_SVLINKY`         |
+| [Svlinky](https://github.com/sadekbaroudi/svlinky)                                       | `svlinky`         | `-e CONVERT_TO=svlinky`         | `CONVERT_TO=svlinky`         | `#ifdef CONVERT_TO_SVLINKY`         |
 
 ### Proton C {#proton_c}
 
@@ -119,26 +103,26 @@ The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is
 
 The following defaults are based on what has been implemented for STM32 boards.
 
-| Feature                                      | Notes                                                                                                            |
+| Feature                                    | Notes                                                                                                          |
-|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
-| [Audio](features/audio)                    | Enabled                                                                                                          |
+| [Audio](features/audio)                    | Enabled                                                                                                        |
-| [RGB Lighting](features/rgblight)          | Disabled                                                                                                         |
+| [RGB Lighting](features/rgblight)          | Disabled                                                                                                       |
 | [Backlight](features/backlight)            | Forces [task driven PWM](features/backlight#software-pwm-driver) until ARM can provide automatic configuration |
-| USB Host (e.g. USB-USB converter)            | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
+| USB Host (e.g. USB-USB converter)          | Not supported (USB host code is AVR specific and is not currently supported on ARM)                            |
-| [Split keyboards](features/split_keyboard) | Partial - heavily dependent on enabled features                                                                  |
+| [Split keyboards](features/split_keyboard) | Partial - heavily dependent on enabled features                                                                |
 
 ### Adafruit KB2040 {#kb2040}
 
 The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040) boards.
 
-| Feature                                      | Notes                                                                                                            |
+| Feature                                    | Notes                                                                                                          |
-|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
-| [RGB Lighting](features/rgblight)          | Enabled via `PIO` vendor driver                                                                                  |
+| [RGB Lighting](features/rgblight)          | Enabled via `PIO` vendor driver                                                                                |
 | [Backlight](features/backlight)            | Forces [task driven PWM](features/backlight#software-pwm-driver) until ARM can provide automatic configuration |
-| USB Host (e.g. USB-USB converter)            | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
+| USB Host (e.g. USB-USB converter)          | Not supported (USB host code is AVR specific and is not currently supported on ARM)                            |
-| [Split keyboards](features/split_keyboard) | Partial via `PIO` vendor driver - heavily dependent on enabled features                                          |
+| [Split keyboards](features/split_keyboard) | Partial via `PIO` vendor driver - heavily dependent on enabled features                                        |
 
-### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#sparkfun_pm2040 }
+### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#sparkfun_pm2040}
 
 Feature set is identical to [Adafruit KB2040](#kb2040).
 
@@ -177,31 +161,193 @@ Feature set is identical to [Adafruit KB2040](#kb2040). VBUS detection is enable
 
 Feature set is a pro micro equivalent of the [RP2040 Community Edition](#rp2040_ce), except that two of the analog GPIO have been replaced with digital only GPIO. These two were moved to the FPC connector to support the [VIK specification](https://github.com/sadekbaroudi/vik). This means that if you are expecting analog support on all 4 pins as provided on a RP2040 Community Edition pinout, you will not have that. Please see the [Svlinky github page](https://github.com/sadekbaroudi/svlinky) for more details.
 
-## Elite-C
+## Elite-C Converters
 
-If a board currently supported in QMK uses an [Elite-C](https://keeb.io/products/elite-c-low-profile-version-usb-c-pro-micro-replacement-atmega32u4), the supported alternative controllers are:
+If a board currently supported by QMK uses an [Elite-C](https://keeb.io/products/elite-c-low-profile-version-usb-c-pro-micro-replacement-atmega32u4), the supported alternative controllers are:
 
-| Device                                                                           | Target            |
+| Device                                                                           | Target      | CLI Argument              | `rules.mk`             | Condition                     |
-|----------------------------------------------------------------------------------|-------------------|
+|----------------------------------------------------------------------------------|-------------|---------------------------|------------------------|-------------------------------|
-| [STeMCell](https://github.com/megamind4089/STeMCell)                             | `stemcell`        |
+| [STeMCell](https://github.com/megamind4089/STeMCell)                             | `stemcell`  | `-e CONVERT_TO=stemcell`  | `CONVERT_TO=stemcell`  | `#ifdef CONVERT_TO_STEMCELL`  |
-| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi`        |
+| [RP2040 Community Edition](#rp2040_ce_elite)                                     | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
-| [0xCB Helios](https://keeb.supply/products/0xcb-helios)                          | `helios`          |
+| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi`  | `-e CONVERT_TO=elite_pi`  | `CONVERT_TO=elite_pi`  | `#ifdef CONVERT_TO_ELITE_PI`  |
-| [Liatris](https://splitkb.com/products/liatris)                                  | `liatris`         |
+| [0xCB Helios](https://keeb.supply/products/0xcb-helios)                          | `helios`    | `-e CONVERT_TO=helios`    | `CONVERT_TO=helios`    | `#ifdef CONVERT_TO_HELIOS`    |
+| [Liatris](https://splitkb.com/products/liatris)                                  | `liatris`   | `-e CONVERT_TO=liatris`   | `CONVERT_TO=liatris`   | `#ifdef CONVERT_TO_LIATRIS`   |
 
-Converter summary:
+### STeMCell {#stemcell_elite}
-
-| Target            | Argument                        | `rules.mk`                   | Condition                           |
-|-------------------|---------------------------------|------------------------------|-------------------------------------|
-| `stemcell`        | `-e CONVERT_TO=stemcell`        | `CONVERT_TO=stemcell`        | `#ifdef CONVERT_TO_STEMCELL`        |
-| `rp2040_ce`       | `-e CONVERT_TO=rp2040_ce`       | `CONVERT_TO=rp2040_ce`       | `#ifdef CONVERT_TO_RP2040_CE`       |
-| `elite_pi`        | `-e CONVERT_TO=elite_pi`        | `CONVERT_TO=elite_pi`        | `#ifdef CONVERT_TO_ELITE_PI`        |
-| `helios`          | `-e CONVERT_TO=helios`          | `CONVERT_TO=helios`          | `#ifdef CONVERT_TO_HELIOS`          |
-| `liatris`         | `-e CONVERT_TO=liatris`         | `CONVERT_TO=liatris`         | `#ifdef CONVERT_TO_LIATRIS`         |
-
-### STeMCell {#stemcell}_elite
 
 Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins.
 
 ### RP2040 Community Edition {#rp2040_ce_elite}
 
 Identical to [Pro Micro - RP2040 Community Edition](#rp2040_ce) with support for the additional bottom row of pins.
+
+## Advanced Topics
+
+### Keyboard Configuration
+
+To configure a keyboard to allow the converter feature, add the following line to your keyboard's `.json` configuration:
+
+```json [keyboard.json]
+{
+    "maintainer": "QMK",
+    "development_board": "promicro", // [!code focus]
+    "diode_direction": "COL2ROW",
+}
+```
+
+See the [pin compatibility](#pin_compatible) for more information.
+
+#### Additional Requirements {#keyboard-req}
+
+Keyboards must use the platform agnostic abstractions provided by QMK. This includes:
+
+* Use of [GPIO Controls](drivers/gpio).
+
+### Additional Keymap Configuration {#keymap-add}
+
+While effort has been made to make converters as compatible as possible, sometimes additional platform specific configuration is required.
+
+For example, enabling hardware peripherals by adding a keymap level `mcuconf.h` with something like the following:
+```c
+#pragma once
+
+#include_next <mcuconf.h>
+
+#undef RP_SIO_USE_UART0
+#define RP_SIO_USE_UART0 TRUE
+```
+
+You can find details on how to configure drivers on their respective pages.
+
+Alternatively, you may have to disable incompatible features. For example:
+
+:::::tabs
+
+==== keymap.json
+
+```json [keymap.json]
+{
+    "version": 1,
+    "keyboard": "keebio/bdn9/rev1",
+    "keymap": "keebio_bdn9_rev1_layout_2025-05-20",
+    "converter": "proton_c",
+    "config": { // [!code focus]
+        "features": { // [!code focus]
+            "audio": false // [!code focus]
+        }
+    }
+    "layout": "LAYOUT",
+}
+```
+
+==== rules.mk
+
+```makefile
+AUDIO_ENABLE = no
+```
+
+:::::
+
+### Conditional Configuration
+
+Once a converter is enabled, it exposes the `CONVERT_TO_<target_uppercase>` flag that you can use in your code with `#ifdef`s, For example:
+
+```c
+#ifdef CONVERT_TO_PROTON_C
+    // Proton C code
+#else
+    // Pro Micro code
+#endif
+```
+
+### Pin Compatibility {#pin_compatible}
+
+To ensure compatibility, provide validation, and power future workflows, a keyboard should declare its `pin compatibility`. This ensures that only valid combinations are attempted.
+
+::: tip Note
+This will already be configured for you if are using the `promicro` development board preset.
+:::
+
+To declare the base interface for conversions, add the following line to your keyboard's configuration:
+
+```json [keyboard.json]
+{
+    "maintainer": "QMK",
+    "development_board": "elite_c", // [!code focus]
+    "pin_compatible": "elite_c", // [!code focus]
+    "diode_direction": "COL2ROW",
+}
+```
+
+The above example, configures a keyboard for a default of `elite_c` while allowing any of the `elite_c` converter targets.
+
+The framework then allows mapping of pins from `<PIN_COMPATIBLE>` to converter `<target>`.
+
+::: warning
+Mapped pins should adhere strictly to the defined interface, any extras present on the hardware should be ignored.
+:::
+
+#### Available Pin Compatibility
+
+:::::tabs
+
+==== promicro
+
+![promicro](/pin_compatible_promicro.svg)
+
+<!-- ```svgbob
+          pins
+     .-------------.           LEDs
+    |               |      _|_       _|_
+D3 -+-O             |      \ /B0     \ /D5
+D2 -+-O             |      -+-       -+-
+    |               |       |         |
+    |               |
+D1 -+-O           O-+- F4
+D0 -+-O           O-+- F5
+D4 -+-O           O-+- F6
+C6 -+-O           O-+- F7
+D7 -+-O           O-+- B1
+E6 -+-O           O-+- B3
+B4 -+-O           O-+- B2
+B5 -+-O           O-+- B6
+    |               |
+    '---+-+-+-+-+---'
+``` -->
+
+::: info Notes:
+Includes LEDs - these may be mapped to unused/unavailable pins when not present.
+:::
+
+==== elite_c
+
+![elite_c](/pin_compatible_elite_c.svg)
+
+<!-- ```svgbob
+          pins
+     .-------------.
+    |               |
+D3 -+-O             |
+D2 -+-O             |
+    |               |
+    |               |
+D1 -+-O           O-+- F4
+D0 -+-O           O-+- F5
+D4 -+-O           O-+- F6
+C6 -+-O           O-+- F7
+D7 -+-O           O-+- B1
+E6 -+-O           O-+- B3
+B4 -+-O           O-+- B2
+B5 -+-O O O O O O O-+- B6
+    |   | | | | |   |
+    '---+-+-+-+-+---'
+        + + + + +
+        B D C F F
+        7 5 7 1 0
+``` -->
+
+::: info Notes:
+Includes bottom row pins, no LEDs.
+:::
+
+:::::

docs/feature_debounce_type.md

@@ -47,7 +47,7 @@ susceptible to noise, you must choose a debounce method that will also mitigate
    * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts.
      This time might be measured in various units:
      * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan
-     * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed.
+     * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does subtraction to figure out time elapsed.
    * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical
      switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard.
    * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the

docs/feature_eeprom.md

@@ -100,7 +100,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
         if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
             if (user_config.rgb_layer_change) {        // only if this is enabled
                 user_config.rgb_layer_change = false;  // disable it, and
-                eeconfig_update_user(user_config.raw); // write the setings to EEPROM
+                eeconfig_update_user(user_config.raw); // write the settings to EEPROM
             }
         }
         return true; break;
@@ -109,7 +109,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   }
 }
 ```
-And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EE_CLR` keycode or [Bootmagic](features/bootmagic) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued.
+And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EE_CLR` keycode or [Bootmagic](features/bootmagic) functionality. For example, if you want to set rgb layer indication by default, and save the default valued.
 
 ```c
 void eeconfig_init_user(void) {  // EEPROM is getting reset!

docs/feature_layers.md

@@ -25,7 +25,7 @@ active layer until pressed again.
 
 Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode.
 
-For a similar reason, the `layer` argument of `LM()` is also limited to layers 0-15 and the `mod` argument must fit within 5 bits. As a consequence, although left and right modifiers are supported by `LM()`, it is impossible to mix and match left and right modifiers. Specifying at least one right-hand modifier in a combination such as `MOD_RALT|MOD_LSFT` will convert *all* the listed modifiers to their right-hand counterpart. So, using the aforementionned mod-mask will actually send <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>. Make sure to use the `MOD_xxx` constants over alternative ways of specifying modifiers when defining your layer-mod key.
+For a similar reason, the `layer` argument of `LM()` is also limited to layers 0-15 and the `mod` argument must fit within 5 bits. As a consequence, although left and right modifiers are supported by `LM()`, it is impossible to mix and match left and right modifiers. Specifying at least one right-hand modifier in a combination such as `MOD_RALT|MOD_LSFT` will convert *all* the listed modifiers to their right-hand counterpart. So, using the aforementioned mod-mask will actually send <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>. Make sure to use the `MOD_xxx` constants over alternative ways of specifying modifiers when defining your layer-mod key.
 
 | `LM(1,KC_LSFT)` | `LM(1,MOD_MASK_SHIFT)` | `LM(1,MOD_BIT(KC_LSFT))` | `LM(1,MOD_LSFT)` |
 |:---------------:|:----------------------:|:------------------------:|:----------------:|
@@ -61,27 +61,27 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta
 
 There are a number of functions (and variables) related to how you can use or manipulate the layers.
 
-|Function                                      |Description                                                                                              |
+|Function                                     |Description                                                                                             |
-|----------------------------------------------|---------------------------------------------------------------------------------------------------------|
+|---------------------------------------------|--------------------------------------------------------------------------------------------------------|
-| `layer_state_set(layer_mask)`                | Directly sets the layer state (avoid unless you know what you are doing).                               |
+|`layer_state_set(layer_mask)`                |Directly sets the layer state (avoid unless you know what you are doing).                               |
-| `layer_clear()`                              | Clears all layers (turns them all off).                                                                 |
+|`layer_clear()`                              |Clears all layers (turns them all off).                                                                 |
-| `layer_move(layer)`                          | Turns specified layer on, and all other layers off.                                                     |
+|`layer_move(layer)`                          |Turns specified layer on, and all other layers off.                                                     |
-| `layer_on(layer)`                            | Turns specified layer on, leaves all other layers in existing state.                                    |
+|`layer_on(layer)`                            |Turns specified layer on, leaves all other layers in existing state.                                    |
-| `layer_off(layer)`                           | Turns specified layer off, leaves all other layers in existing state.                                   |
+|`layer_off(layer)`                           |Turns specified layer off, leaves all other layers in existing state.                                   |
-| `layer_invert(layer)`                        | Inverts/toggles the state of the specified layer                                                        |
+|`layer_invert(layer)`                        |Inverts/toggles the state of the specified layer                                                        |
-| `layer_or(layer_mask)`                       | Turns on layers based on matching bits between specifed layer and existing layer state.                 |
+|`layer_or(layer_mask)`                       |Turns on layers based on matching bits between specified layer and existing layer state.                |
-| `layer_and(layer_mask)`                      | Turns on layers based on matching enabled bits between specifed layer and existing layer state.         |
+|`layer_and(layer_mask)`                      |Turns on layers based on matching enabled bits between specified layer and existing layer state.        |
-| `layer_xor(layer_mask)`                      | Turns on layers based on non-matching bits between specifed layer and existing layer state.             |
+|`layer_xor(layer_mask)`                      |Turns on layers based on non-matching bits between specified layer and existing layer state.            |
-| `layer_debug(layer_mask)`                    | Prints out the current bit mask and highest active layer to debugger console.                           |
+|`layer_debug(layer_mask)`                    |Prints out the current bit mask and highest active layer to debugger console.                           |
-| `default_layer_set(layer_mask)`              | Directly sets the default layer state (avoid unless you know what you are doing).                       |
+|`default_layer_set(layer_mask)`              |Directly sets the default layer state (avoid unless you know what you are doing).                       |
-| `default_layer_or(layer_mask)`               | Turns on layers based on matching bits between specifed layer and existing default layer state.         |
+|`default_layer_or(layer_mask)`               |Turns on layers based on matching bits between specified layer and existing default layer state.        |
-| `default_layer_and(layer_mask)`              | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. |
+|`default_layer_and(layer_mask)`              |Turns on layers based on matching enabled bits between specified layer and existing default layer state.|
-| `default_layer_xor(layer_mask)`              | Turns on layers based on non-matching bits between specifed layer and existing default layer state.     |
+|`default_layer_xor(layer_mask)`              |Turns on layers based on non-matching bits between specified layer and existing default layer state.    |
-| `default_layer_debug(layer_mask)`            | Prints out the current bit mask and highest active default layer to debugger console.                   |
+|`default_layer_debug(layer_mask)`            |Prints out the current bit mask and highest active default layer to debugger console.                   |
-| [`set_single_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer)            | Sets the default layer, but does _not_ write it to persistent memory (EEPROM). | 
+|[`set_single_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer)           |Sets the default layer, but does _not_ write it to persistent memory (EEPROM).                      |
-| [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM).  |
+|[`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer)|Sets the default layer and writes it to persistent memory (EEPROM).                                 |
-| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). |
+|[`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z)                                |Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off).|
-| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. |
+|[`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z)       |Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions.               |
 
 In addition to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passes the layer state to the function, where it can be read or modified.
 

docs/feature_userspace.md

@@ -119,7 +119,8 @@ This is ideal for when you want ensure everything compiles successfully when pre
 ## Examples
 
 For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example).
-For more complicated examples, checkout the [`awesome-qmk` colletion](https://github.com/qmk/awesome-qmk).
+
+For more complicated examples, checkout the [`awesome-qmk` collection](https://github.com/qmk/awesome-qmk).
 
 
 ### Customized Functions
@@ -189,7 +190,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 
 If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too.
 
-First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead.   This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well.   You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes
+First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead.   This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well.   You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you won't have any overlapping keycodes
 
 Then add `#include "<name>.h"` to all of your keymap.c files.  This allows you to use these new keycodes without having to redefine them in each keymap.
 

docs/features/audio.md

@@ -73,16 +73,13 @@ Should you rather choose to generate and use your own sample-table with the DAC
 
 
 ### PWM (software)
-if the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative.
+If the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative.
 Note that there is currently only one speaker/pin supported.
 
-set in `rules.mk`:
+To use this feature, set `AUDIO_DRIVER = pwm_software` in `rules.mk` and set `#define AUDIO_PIN C13` (can be any pin) in `config.h` to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.
-
-`AUDIO_DRIVER = pwm_software` and in `config.h`: 
-`#define AUDIO_PIN C13` (can be any pin) to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.
 
 #### Wiring
-the usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground.
+The usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground.
 
 OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2.
 
@@ -178,8 +175,8 @@ These keycodes turn all of the audio functionality on and off.  Turning it off m
 |`AUDIO_PIN`                       | *Not defined*        |Configures the pin that the speaker is connected to.                                         |
 |`AUDIO_PIN_ALT`                   | *Not defined*        |Configures the pin for a second speaker or second pin connected to one speaker.              |
 |`AUDIO_PIN_ALT_AS_NEGATIVE`       | *Not defined*        |Enables support for one speaker connected to two pins.                                       |
-|`AUDIO_INIT_DELAY`                | *Not defined*        |Enables delay during startup song to accomidate for USB startup issues.                      |
+|`AUDIO_INIT_DELAY`                | *Not defined*        |Enables delay during startup song to accommodate for USB startup issues.                     |
-|`AUDIO_ENABLE_TONE_MULTIPLEXING`  | *Not defined*        |Enables time splicing/multiplexing to create multiple tones simutaneously.                   |
+|`AUDIO_ENABLE_TONE_MULTIPLEXING`  | *Not defined*        |Enables time splicing/multiplexing to create multiple tones simultaneously.                  |
 |`AUDIO_POWER_CONTROL_PIN`         | *Not defined*        |Enables power control code to enable or cut off power to speaker (such as with PAM8302 amp). |
 |`AUDIO_POWER_CONTROL_PIN_ON_STATE`| `1`                  |The state of the audio power control pin when audio is "on" - `1` for high, `0` for low.     |
 |`STARTUP_SONG`                    | `STARTUP_SOUND`      |Plays when the keyboard starts up (audio.c)                                                  |

docs/features/autocorrect.md

@@ -8,7 +8,7 @@ The feature maintains a small buffer of recent key presses. On each key press, i
 
 The tricky part is how to efficiently check the buffer for typos. We don’t want to spend too much memory or time on storing or searching the typos. A good solution is to represent the typos with a trie data structure. A trie is a tree data structure where each node is a letter, and words are formed by following a path to one of the leaves.
 
-![An example trie](https://i.imgur.com/HL5DP8H.png)
+![An example trie](/HL5DP8H.png)
 
 Since we search whether the buffer ends in a typo, we store the trie writing in reverse. The trie is queried starting from the last letter, then second to last letter, and so on, until either a letter doesn’t match or we reach a leaf, meaning a typo was found.
 
@@ -279,7 +279,7 @@ All autocorrection data is stored in a single flat array autocorrect_data. Each
 * 01 ⇒ branching node: a trie node with multiple children.
 * 10 ⇒ leaf node: a leaf, corresponding to a typo and storing its correction.
 
-![An example trie](https://i.imgur.com/HL5DP8H.png)
+![An example trie](/HL5DP8H.png)
 
 **Branching node**. Each branch is encoded with one byte for the keycode (KC_A–KC_Z) followed by a link to the child node. Links between nodes are 16-bit byte offsets relative to the beginning of the array, serialized in little endian order.
 

docs/features/backlight.md

@@ -227,7 +227,7 @@ In this typical example, the backlight LEDs are all connected in parallel toward
 A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU.
 The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information.
 
-![Backlight example circuit](https://i.imgur.com/BmAvoUC.png)
+![Backlight example circuit](/BmAvoUC.png)
 
 ## API {#api}
 

docs/features/battery.md

@@ -0,0 +1,55 @@
+# Battery
+
+This feature provides the high level abstraction for sampling battery level.
+
+## Usage
+
+To use this driver, add the following to your `rules.mk`:
+
+```make
+BATTERY_ENABLE = yes
+```
+
+## Basic Configuration {#basic-configuration}
+
+Add the following to your `config.h`:
+
+|Define                    |Default |Description                                       |
+|--------------------------|--------|--------------------------------------------------|
+|`BATTERY_SAMPLE_INTERVAL` |`30000` |The time between battery samples in milliseconds. |
+
+## Driver Configuration {#driver-configuration}
+
+See the [Battery Driver](../drivers/battery) documentation for more information.
+
+## Functions
+
+### `uint8_t battery_get_percent(void)` {#api-battery-get-percent}
+
+Sample battery level.
+
+#### Return Value {#api-battery-get-percent-return}
+
+The battery percentage, in the range 0-100.
+
+## Callbacks
+
+### `void battery_percent_changed_user(uint8_t level)` {#api-battery-percent-changed-user}
+
+User hook called when battery level changed.
+
+### Arguments {#api-battery-percent-changed-user-arguments}
+
+ - `uint8_t level`  
+   The battery percentage, in the range 0-100.
+
+---
+
+### `void battery_percent_changed_kb(uint8_t level)` {#api-battery-percent-changed-kb}
+
+Keyboard hook called when battery level changed.
+
+### Arguments {#api-battery-percent-changed-kb-arguments}
+
+ - `uint8_t level`  
+   The battery percentage, in the range 0-100.

docs/features/bootmagic.md

@@ -46,7 +46,7 @@ When [handedness](split_keyboard#setting-handedness) is predetermined via option
     }
 ```
 
-If you pick the top right key for the right half, it is `R05` on the top layout. Within the key matrix below, `R05` is located on row 4 columnn 4. To use that key as the right half's Bootmagic trigger, add these entries to your `config.h` file:
+If you pick the top right key for the right half, it is `R05` on the top layout. Within the key matrix below, `R05` is located on row 4 column 4. To use that key as the right half's Bootmagic trigger, add these entries to your `config.h` file:
 
 ```c
 #define BOOTMAGIC_ROW_RIGHT 4

docs/features/dynamic_macros.md

@@ -32,12 +32,13 @@ For the details about the internals of the dynamic macros, please read the comme
 
 There are a number of options added that should allow some additional degree of customization
 
-|Define                      |Default         |Description                                                                                                      |
+|Define                                    |Default         |Description                                                                                                      |
-|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
+|------------------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
-|`DYNAMIC_MACRO_SIZE`        |128             |Sets the amount of memory that Dynamic Macros can use. This is a limited resource, dependent on the controller.  |
+|`DYNAMIC_MACRO_SIZE`                      |128             |Sets the amount of memory that Dynamic Macros can use. This is a limited resource, dependent on the controller.  |
-|`DYNAMIC_MACRO_USER_CALL`   |*Not defined*   |Defining this falls back to using the user `keymap.c` file to trigger the macro behavior.                        |
+|`DYNAMIC_MACRO_USER_CALL`                 |*Not defined*   |Defining this falls back to using the user `keymap.c` file to trigger the macro behavior.                        |
-|`DYNAMIC_MACRO_NO_NESTING`  |*Not Defined*   |Defining this disables the ability to call a macro from another macro (nested macros).                           | 
+|`DYNAMIC_MACRO_NO_NESTING`                |*Not Defined*   |Defining this disables the ability to call a macro from another macro (nested macros).                           |
-|`DYNAMIC_MACRO_DELAY`        |*Not Defined*   |Sets the waiting time (ms unit) when sending each key.                                                           |
+|`DYNAMIC_MACRO_DELAY`                     |*Not Defined*   |Sets the waiting time (ms unit) when sending each key.                                                           |
+|`DYNAMIC_MACRO_KEEP_ORIGINAL_LAYER_STATE` |*Not Defined*   |Defining this keeps the layer state when starting to record a macro                                              |
 
 
 If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by adding the `DYNAMIC_MACRO_SIZE` define in your `config.h` (default value: 128; please read the comments for it in the header).

docs/features/encoders.md

@@ -68,7 +68,7 @@ Additionally, if one side does not have an encoder, you can specify `{}` for the
 ```
 
 ::: warning
-Keep in mind that whenver you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change.
+Keep in mind that whenever you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change.
 :::
 
 ## Encoder map {#encoder-map}

docs/features/haptic_feedback.md

@@ -44,8 +44,8 @@ Not all keycodes below will work depending on which haptic mechanism you have ch
 |`QK_HAPTIC_MODE_NEXT`        |`HF_NEXT`| Go to next DRV2605L waveform                          |
 |`QK_HAPTIC_MODE_PREVIOUS`    |`HF_PREV`| Go to previous DRV2605L waveform                      |
 |`QK_HAPTIC_CONTINUOUS_TOGGLE`|`HF_CONT`| Toggle continuous haptic mode on/off                  |
-|`QK_HAPTIC_CONTINUOUS_UP`    |`HF_CONU`| Increase DRV2605L continous haptic strength           |
+|`QK_HAPTIC_CONTINUOUS_UP`    |`HF_CONU`| Increase DRV2605L continuous haptic strength          |
-|`QK_HAPTIC_CONTINUOUS_DOWN`  |`HF_COND`| Decrease DRV2605L continous haptic strength           |
+|`QK_HAPTIC_CONTINUOUS_DOWN`  |`HF_COND`| Decrease DRV2605L continuous haptic strength          |
 |`QK_HAPTIC_DWELL_UP`         |`HF_DWLU`| Increase Solenoid dwell time                          |
 |`QK_HAPTIC_DWELL_DOWN`       |`HF_DWLD`| Decrease Solenoid dwell time                          |
 
@@ -75,7 +75,7 @@ For relay switches, the hardware may already contain all of that ciruitry, and j
 |`SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` |Non-Actuated-time when the switch is in buzz mode.            |
 
 * If solenoid buzz is off, then dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds.
-* If solenoid buzz is on, then dwell time sets the length of the buzz, while `SOLENOID_BUZZ_ACTUATED` and `SOLENOID_BUZZ_NONACTUATED` set the (non-)actuation times withing the buzz period.
+* If solenoid buzz is on, then dwell time sets the length of the buzz, while `SOLENOID_BUZZ_ACTUATED` and `SOLENOID_BUZZ_NONACTUATED` set the (non-)actuation times within the buzz period.
 * With the current implementation, for any of the above time settings, the precision of these settings may be affected by how fast the keyboard is able to scan the matrix.
   Therefore, if the keyboards scanning routine is slow, it may be preferable to set `SOLENOID_DWELL_STEP_SIZE` to a value slightly smaller than the time it takes to scan the keyboard.
 
@@ -104,7 +104,7 @@ Eccentric Rotating Mass vibration motors (ERM) is motor with a off-set weight at
 ```
 ##### LRA
 
-Linear resonant actuators (LRA, also know as a linear vibrator) works different from a ERM. A LRA has a weight and magnet suspended by springs and a voice coil. When the drive signal is applied, the weight would be vibrate on a single axis (side to side or up and down). Since the weight is attached to a spring, there is a resonance effect at a specific frequency. This frequency is where the LRA will operate the most efficiently. Refer to the motor's datasheet for the recommanded range for this frequency.
+Linear resonant actuators (LRA, also know as a linear vibrator) works different from a ERM. A LRA has a weight and magnet suspended by springs and a voice coil. When the drive signal is applied, the weight would be vibrate on a single axis (side to side or up and down). Since the weight is attached to a spring, there is a resonance effect at a specific frequency. This frequency is where the LRA will operate the most efficiently. Refer to the motor's datasheet for the recommended range for this frequency.
 
 ```c
 #define DRV2605L_FB_ERM_LRA 1
@@ -121,11 +121,11 @@ Linear resonant actuators (LRA, also know as a linear vibrator) works different
 
 #### DRV2605L waveform library
 
-DRV2605L comes with preloaded library of various waveform sequences that can be called and played. If writing a macro, these waveforms can be played using `DRV_pulse(*sequence name or number*)`
+DRV2605L comes with preloaded library of various waveform sequences that can be called and played. If writing a macro, these waveforms can be played using `drv2605l_pulse(*sequence name or number*)` after adding `#include "drv2605l.h"`.
 
 List of waveform sequences from the datasheet:
 
-|seq# | Sequence name          |seq# | Sequence name                  |seq# |Sequence name                           |
+|seq# | Sequence name       |seq# | Sequence name                     |seq# |Sequence name                         |
 |-----|---------------------|-----|-----------------------------------|-----|--------------------------------------|
 | 1   | strong_click 		| 43  | lg_dblclick_med_60                | 85  | transition_rampup_med_smooth2        |
 | 2   | strong_click_60 	| 44  | lg_dblsharp_tick                  | 86  | transition_rampup_short_smooth1      |

docs/features/layer_lock.md

@@ -35,12 +35,12 @@ layer.
 
 Consider a keymap with the following base layer.
 
-![Base layer with a MO(NAV) key.](https://i.imgur.com/DkEhj9x.png)
+![Base layer with a MO(NAV) key.](/DkEhj9x.png)
 
 The highlighted key is a momentary layer switch `MO(NAV)`. Holding it accesses a
 navigation layer.
 
-![Nav layer with a Layer Lock key.](https://i.imgur.com/2wUZNWk.png)
+![Nav layer with a Layer Lock key.](/2wUZNWk.png)
 
 
 Holding the NAV key is fine for brief use, but awkward to continue holding when

docs/features/led_matrix.md

@@ -88,6 +88,8 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
 |`QK_LED_MATRIX_BRIGHTNESS_DOWN`|`LM_BRID`|Decrease the brightness level      |
 |`QK_LED_MATRIX_SPEED_UP`       |`LM_SPDU`|Increase the animation speed       |
 |`QK_LED_MATRIX_SPEED_DOWN`     |`LM_SPDD`|Decrease the animation speed       |
+|`QK_LED_MATRIX_FLAG_NEXT`      |`LM_FLGN`|Cycle through flags                |
+|`QK_LED_MATRIX_FLAG_PREVIOUS`  |`LM_FLGP`|Cycle through flags in reverse     |
 
 ## LED Matrix Effects {#led-matrix-effects}
 
@@ -214,9 +216,30 @@ led_matrix_mode(LED_MATRIX_CUSTOM_my_cool_effect);
 For inspiration and examples, check out the built-in effects under `quantum/led_matrix/animations/`.
 
 
+## Naming
+
+If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `led_matrix_get_mode_name` in the following manner:
+
+In your keymap's `config.h`:
+```c
+#define LED_MATRIX_MODE_NAME_ENABLE
+```
+
+In your `keymap.c`
+```c
+const char* effect_name = led_matrix_get_mode_name(led_matrix_get_mode());
+// do something with `effect_name`, like `oled_write_ln(effect_name, false);`
+```
+
+::: info
+`led_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled.
+:::
+
+
 ## Additional `config.h` Options {#additional-configh-options}
 
 ```c
+#define LED_MATRIX_MODE_NAME_ENABLE // enables led_matrix_get_mode_name()
 #define LED_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses)
 #define LED_MATRIX_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off
 #define LED_MATRIX_SLEEP // turn off effects when suspended
@@ -232,6 +255,7 @@ For inspiration and examples, check out the built-in effects under `quantum/led_
 #define LED_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set
 #define LED_MATRIX_SPLIT { X, Y }   // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
                                     // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
+#define LED_MATRIX_FLAG_STEPS { LED_FLAG_ALL, LED_FLAG_KEYLIGHT | LED_FLAG_MODIFIER, LED_FLAG_NONE } // Sets the flags which can be cycled through.
 ```
 
 ## EEPROM storage {#eeprom-storage}
@@ -484,6 +508,62 @@ The current effect speed, from 0 to 255.
 
 ---
 
+### `void led_matrix_set_flags(led_flags_t flags)` {#api-led-matrix-set-flags}
+
+Set the global effect flags.
+
+#### Arguments {#api-led-matrix-set-flags-arguments}
+
+ - `led_flags_t flags`  
+   The [flags](#flags) value to set.
+
+---
+
+### `void led_matrix_set_flags_noeeprom(led_flags_t flags)` {#api-led-matrix-set-flags-noeeprom}
+
+Set the global effect flags. New state is not written to EEPROM.
+
+#### Arguments {#api-led-matrix-set-flags-noeeprom-arguments}
+
+ - `led_flags_t flags`  
+   The [flags](#flags) value to set.
+
+---
+
+### `void led_matrix_flags_step(void)` {#api-led-matrix-flags-step}
+
+Move to the next flag combination.
+
+---
+
+### `void led_matrix_flags_step_noeeprom(void)` {#api-led-matrix-flags-step-noeeprom}
+
+Move to the next flag combination. New state is not written to EEPROM.
+
+---
+
+### `void led_matrix_flags_step_reverse(void)` {#api-led-matrix-flags-step-reverse}
+
+Move to the previous flag combination.
+
+---
+
+### `void led_matrix_flags_step_reverse_noeeprom(void)` {#api-led-matrix-flags-step-reverse-noeeprom}
+
+Move to the previous flag combination. New state is not written to EEPROM.
+
+---
+
+### `uint8_t led_matrix_get_flags(void)` {#api-led-matrix-get-flags}
+
+Get the current global effect flags.
+
+#### Return Value {#api-led-matrix-get-flags-return}
+
+The current effect [flags](#flags).
+
+---
+
 ### `void led_matrix_reload_from_eeprom(void)` {#api-led-matrix-reload-from-eeprom}
 
 Reload the effect configuration (enabled, mode and brightness) from EEPROM.

docs/features/pointing_device.md

@@ -267,6 +267,23 @@ The paw 3204 sensor uses a serial type protocol for communication, and requires
 
 The CPI range is 400-1600, with supported values of (400, 500, 600, 800, 1000, 1200 and 1600).  Defaults to 1000 CPI.
 
+### PAW-3222 Sensor
+
+To use the PAW-3222 sensor, add this to your `rules.mk`:
+
+```make
+POINTING_DEVICE_DRIVER = paw3222
+```
+
+The following pins must be defined in `config.h`:
+
+| Setting (`config.h`)  | Description                                                        | Default                      |
+| --------------------- | ------------------------------------------------------------------ | ---------------------------- |
+| `PAW3222_CS_PIN`      | (Required) The pin connected to the chip select pin of the sensor. | `POINTING_DEVICE_CS_PIN`     |
+| `PAW3222_SPI_DIVISOR` | (Required) The SPI clock divisor. This is dependent on your MCU.   | _not defined_                |
+
+The CPI range is up to 4,000. Defaults to 1,000 CPI.
+
 ### Pimoroni Trackball
 
 To use the Pimoroni Trackball module, add this to your `rules.mk`:
@@ -379,7 +396,7 @@ POINTING_DEVICE_DRIVER = custom
 Using the custom driver will require implementing the following functions:
 
 ```c
-void           pointing_device_driver_init(void) {}
+bool           pointing_device_driver_init(void) { return true; }
 report_mouse_t pointing_device_driver_get_report(report_mouse_t mouse_report) { return mouse_report; }
 uint16_t       pointing_device_driver_get_cpi(void) { return 0; }
 void           pointing_device_driver_set_cpi(uint16_t cpi) {}
@@ -424,7 +441,7 @@ Any pointing device with a lift/contact status can integrate inertial cursor fea
 | Setting                                  | Description                                                                                                               | Default       |
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- |
 | `POINTING_DEVICE_HIRES_SCROLL_ENABLE`    | (Optional) Enables high resolution scrolling.                                                                             | _not defined_ |
-| `POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER`| (Optional) Resolution mutiplier value used by high resolution scrolling. Must be between 1 and 127, inclusive.            | `120`         |
+| `POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER`| (Optional) Resolution multiplier value used by high resolution scrolling. Must be between 1 and 127, inclusive.           | `120`         |
 | `POINTING_DEVICE_HIRES_SCROLL_EXPONENT`  | (Optional) Resolution exponent value used by high resolution scrolling. Must be between 0 and 127, inclusive.             | `0`           |
 
 The `POINTING_DEVICE_HIRES_SCROLL_ENABLE` setting enables smooth and continuous scrolling when using trackballs or high-end encoders as mouse wheels (as opposed to the typical stepped behavior of most mouse wheels).
@@ -467,20 +484,22 @@ If there is a `_RIGHT` configuration option or callback, the [common configurati
 
 ## Callbacks and Functions
 
-| Function                                                   | Description                                                                                                   |
+| Function                                                      | Description                                                                                                   |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `pointing_device_init_kb(void)`                            | Callback to allow for keyboard level initialization. Useful for additional hardware sensors.                  |
+| `pointing_device_init_kb(void)`                               | Callback to allow for keyboard level initialization. Useful for additional hardware sensors.                  |
-| `pointing_device_init_user(void)`                          | Callback to allow for user level initialization. Useful for additional hardware sensors.                      |
+| `pointing_device_init_user(void)`                             | Callback to allow for user level initialization. Useful for additional hardware sensors.                      |
-| `pointing_device_task_kb(mouse_report)`                    | Callback that sends sensor data, so keyboard code can intercept and modify the data.  Returns a mouse report. |
+| `pointing_device_task_kb(mouse_report)`                       | Callback that sends sensor data, so keyboard code can intercept and modify the data.  Returns a mouse report. |
-| `pointing_device_task_user(mouse_report)`                  | Callback that sends sensor data, so user code can intercept and modify the data.  Returns a mouse report.     |
+| `pointing_device_task_user(mouse_report)`                     | Callback that sends sensor data, so user code can intercept and modify the data.  Returns a mouse report.     |
-| `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`.                                              |
+| `pointing_device_handle_buttons(buttons, pressed, button)`    | Callback to handle hardware button presses. Returns a `uint8_t`.                                              |
-| `pointing_device_get_cpi(void)`                            | Gets the current CPI/DPI setting from the sensor, if supported.                                               |
+| `pointing_device_get_cpi(void)`                               | Gets the current CPI/DPI setting from the sensor, if supported.                                               |
-| `pointing_device_set_cpi(uint16_t)`                        | Sets the CPI/DPI, if supported.                                                                               |
+| `pointing_device_set_cpi(uint16_t)`                           | Sets the CPI/DPI, if supported.                                                                               |
-| `pointing_device_get_report(void)`                         | Returns the current mouse report (as a `report_mouse_t` data structure).                                      |
+| `pointing_device_get_report(void)`                            | Returns the current mouse report (as a `report_mouse_t` data structure).                                      |
-| `pointing_device_set_report(mouse_report)`                 | Sets the mouse report to the assigned `report_mouse_t` data structured passed to the function.                |
+| `pointing_device_set_report(mouse_report)`                    | Sets the mouse report to the assigned `report_mouse_t` data structured passed to the function.                |
-| `pointing_device_send(void)`                               | Sends the current mouse report to the host system.  Function can be replaced.                                 |
+| `pointing_device_send(void)`                                  | Sends the current mouse report to the host system.  Function can be replaced.                                 |
-| `has_mouse_report_changed(new_report, old_report)`         | Compares the old and new `report_mouse_t` data and returns true only if it has changed.                       |
+| `has_mouse_report_changed(new_report, old_report)`            | Compares the old and new `report_mouse_t` data and returns true only if it has changed.                       |
-| `pointing_device_adjust_by_defines(mouse_report)`          | Applies rotations and invert configurations to a raw mouse report.                                            |
+| `pointing_device_adjust_by_defines(mouse_report)`             | Applies rotations and invert configurations to a raw mouse report.                                            |
+| `pointing_device_get_status(void)`                            | Returns device status as `pointing_device_status_t` a good return is `POINTING_DEVICE_STATUS_SUCCESS`.        |
+| `pointing_device_set_status(pointing_device_status_t status)` | Sets device status, anything other than `POINTING_DEVICE_STATUS_SUCCESS` will disable reports from the device.|
 
 
 ## Split Keyboard Callbacks and Functions
@@ -753,6 +772,7 @@ void pointing_device_init_user(void) {
 ```
 
 Because the auto mouse feature can be disabled/enabled during runtime and starts as disabled by default it must be enabled by calling `set_auto_mouse_enable(true);` somewhere in firmware before the feature will work.
+
 _Note: for setting the target layer during initialization either setting `AUTO_MOUSE_DEFAULT_LAYER` in `config.h` or calling `set_auto_mouse_layer(<mouse_layer>)` can be used._
 
 
@@ -824,9 +844,10 @@ There are several functions that allow for more advanced interaction with the au
 | `set_auto_mouse_key_tracker(int8_t key_tracker)`           | Sets/Overrides the current count for the auto mouse key tracker.                     |                           |    `void`(None) |
 
 _NOTES:_
-    - _Due to the nature of how some functions work, the `auto_mouse_trigger_reset`, and `auto_mouse_layer_off` functions should never be called in the `layer_state_set_*` stack as this can cause indefinite loops._   
+
-    - _It is recommended that `remove_auto_mouse_layer` is used in the `layer_state_set_*` stack of functions and `auto_mouse_layer_off` is used everywhere else_   
+- _Due to the nature of how some functions work, the `auto_mouse_trigger_reset`, and `auto_mouse_layer_off` functions should never be called in the `layer_state_set_*` stack as this can cause indefinite loops._
-    - _`remove_auto_mouse_layer(state, false)` or `auto_mouse_layer_off()` should be called before any instance of `set_auto_mouse_enabled(false)` or `set_auto_mouse_layer(layer)` to ensure that the target layer will be removed appropriately before disabling auto mouse or changing target to avoid a stuck layer_      
+- _It is recommended that `remove_auto_mouse_layer` is used in the `layer_state_set_*` stack of functions and `auto_mouse_layer_off` is used everywhere else_
+- _`remove_auto_mouse_layer(state, false)` or `auto_mouse_layer_off()` should be called before any instance of `set_auto_mouse_enabled(false)` or `set_auto_mouse_layer(layer)` to ensure that the target layer will be removed appropriately before disabling auto mouse or changing target to avoid a stuck layer_
 
 ### Functions for handling custom key events:
 | Function                                                   | Description                                                                      |     Return type |
@@ -835,6 +856,7 @@ _NOTES:_
 | `auto_mouse_trigger_reset(bool pressed)`                   | Reset auto mouse status on key down and start delay timer (non-mouse key event)  |    `void`(None) |
 | `auto_mouse_toggle(void)`                                  | Toggle on/off target toggle state (disables layer deactivation when true)        |    `void`(None) |
 | `get_auto_mouse_toggle(void)`                              | Return value of toggling state variable                                          |          `bool` |
+
 _NOTE: Generally it would be preferable to use the `is_mouse_record_*` functions to add any additional keys that should act as mouse keys rather than adding `auto_mouse_keyevent(record.event->pressed)` to `process_records_*`_
 
 ### Advanced control examples
@@ -891,7 +913,9 @@ layer_state_t default_layer_state_set_user(layer_state_t state) {
 ```
 
 ### Use custom keys to control auto mouse:
+
 Custom key records could also be created that control the auto mouse feature.
+
 The code example below would create a custom key that would toggle the auto mouse feature on and off when pressed while also setting a bool that could be used to disable other code that may turn it on such as the layer code above.
 
 ```c

docs/features/repeat_key.md

@@ -178,7 +178,7 @@ dedicate keys to them. The following defines a couple shortcuts.
 * Typing <kbd>K</kbd>, <kbd>Alt Repeat</kbd> produces "`keyboard`," with the
   initial "`k`" typed as usual and the "`eybord`" produced by the macro.
 * Typing <kbd>.</kbd>, <kbd>Alt Repeat</kbd> produces "`../`," handy for "up
-  directory" on the shell. Similary, <kbd>.</kbd> types the initial "`.`" and 
+  directory" on the shell. Similarly, <kbd>.</kbd> types the initial "`.`" and
   "`./`" is produced by the macro.
 
 ```c

docs/features/rgb_matrix.md

@@ -96,6 +96,8 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
 |`QK_RGB_MATRIX_VALUE_DOWN`     |`RM_VALD`|Decrease the brightness level      |
 |`QK_RGB_MATRIX_SPEED_UP`       |`RM_SPDU`|Increase the animation speed       |
 |`QK_RGB_MATRIX_SPEED_DOWN`     |`RM_SPDD`|Decrease the animation speed       |
+|`QK_RGB_MATRIX_FLAG_NEXT`      |`RM_FLGN`|Cycle through flags                |
+|`QK_RGB_MATRIX_FLAG_PREVIOUS`  |`RM_FLGP`|Cycle through flags in reverse     |
 
 ## RGB Matrix Effects {#rgb-matrix-effects}
 
@@ -125,13 +127,13 @@ enum rgb_matrix_effects {
     RGB_MATRIX_CYCLE_SPIRAL,        // Full gradient spinning spiral around center of keyboard
     RGB_MATRIX_DUAL_BEACON,         // Full gradient spinning around center of keyboard
     RGB_MATRIX_RAINBOW_BEACON,      // Full tighter gradient spinning around center of keyboard
-    RGB_MATRIX_RAINBOW_PINWHEELS,   // Full dual gradients spinning two halfs of keyboard
+    RGB_MATRIX_RAINBOW_PINWHEELS,   // Full dual gradients spinning two halves of keyboard
     RGB_MATRIX_FLOWER_BLOOMING,     // Full tighter gradient of first half scrolling left to right and second half scrolling right to left
     RGB_MATRIX_RAINDROPS,           // Randomly changes a single key's hue
     RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation
-    RGB_MATRIX_HUE_BREATHING,       // Hue shifts up a slight ammount at the same time, then shifts back
+    RGB_MATRIX_HUE_BREATHING,       // Hue shifts up a slight amount at the same time, then shifts back
-    RGB_MATRIX_HUE_PENDULUM,        // Hue shifts up a slight ammount in a wave to the right, then back to the left
+    RGB_MATRIX_HUE_PENDULUM,        // Hue shifts up a slight amount in a wave to the right, then back to the left
-    RGB_MATRIX_HUE_WAVE,            // Hue shifts up a slight ammount and then back down in a wave to the right
+    RGB_MATRIX_HUE_WAVE,            // Hue shifts up a slight amount and then back down in a wave to the right
     RGB_MATRIX_PIXEL_FRACTAL,       // Single hue fractal filled keys pulsing horizontally out to edges
     RGB_MATRIX_PIXEL_FLOW,          // Pulsing RGB flow along LED wiring with random hues
     RGB_MATRIX_PIXEL_RAIN,          // Randomly light keys with random hues
@@ -365,9 +367,30 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set
 These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
 
 
+## Naming
+
+If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `rgb_matrix_get_mode_name` in the following manner:
+
+In your keymap's `config.h`:
+```c
+#define RGB_MATRIX_MODE_NAME_ENABLE
+```
+
+In your `keymap.c`
+```c
+const char* effect_name = rgb_matrix_get_mode_name(rgb_matrix_get_mode());
+// do something with `effect_name`, like `oled_write_ln(effect_name, false);`
+```
+
+::: info
+`rgb_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled.
+:::
+
+
 ## Additional `config.h` Options {#additional-configh-options}
 
 ```c
+#define RGB_MATRIX_MODE_NAME_ENABLE // enables rgb_matrix_get_mode_name()
 #define RGB_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses)
 #define RGB_MATRIX_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off
 #define RGB_MATRIX_SLEEP // turn off effects when suspended
@@ -385,9 +408,10 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master
 #define RGB_MATRIX_VAL_STEP 16 // The value by which to increment the brightness per adjustment action
 #define RGB_MATRIX_SPD_STEP 16 // The value by which to increment the animation speed per adjustment action
 #define RGB_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set
-#define RGB_MATRIX_SPLIT { X, Y } 	// (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
+#define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
-                              		// If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
+                                  // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
 #define RGB_TRIGGER_ON_KEYDOWN      // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards
+#define RGB_MATRIX_FLAG_STEPS { LED_FLAG_ALL, LED_FLAG_KEYLIGHT | LED_FLAG_MODIFIER, LED_FLAG_UNDERGLOW, LED_FLAG_NONE } // Sets the flags which can be cycled through.
 ```
 
 ## EEPROM storage {#eeprom-storage}
@@ -831,6 +855,62 @@ The current effect speed, from 0 to 255.
 
 ---
 
+### `void rgb_matrix_set_flags(led_flags_t flags)` {#api-rgb-matrix-set-flags}
+
+Set the global effect flags.
+
+#### Arguments {#api-rgb-matrix-set-flags-arguments}
+
+ - `led_flags_t flags`  
+   The [flags](#flags) value to set.
+
+---
+
+### `void rgb_matrix_set_flags_noeeprom(led_flags_t flags)` {#api-rgb-matrix-set-flags-noeeprom}
+
+Set the global effect flags. New state is not written to EEPROM.
+
+#### Arguments {#api-rgb-matrix-set-flags-noeeprom-arguments}
+
+ - `led_flags_t flags`  
+   The [flags](#flags) value to set.
+
+---
+
+### `void rgb_matrix_flags_step(void)` {#api-rgb-matrix-flags-step}
+
+Move to the next flag combination.
+
+---
+
+### `void rgb_matrix_flags_step_noeeprom(void)` {#api-rgb-matrix-flags-step-noeeprom}
+
+Move to the next flag combination. New state is not written to EEPROM.
+
+---
+
+### `void rgb_matrix_flags_step_reverse(void)` {#api-rgb-matrix-flags-step-reverse}
+
+Move to the previous flag combination.
+
+---
+
+### `void rgb_matrix_flags_step_reverse_noeeprom(void)` {#api-rgb-matrix-flags-step-reverse-noeeprom}
+
+Move to the previous flag combination. New state is not written to EEPROM.
+
+---
+
+### `uint8_t rgb_matrix_get_flags(void)` {#api-rgb-matrix-get-flags}
+
+Get the current global effect flags.
+
+#### Return Value {#api-rgb-matrix-get-flags-return}
+
+The current effect [flags](#flags).
+
+---
+
 ### `void rgb_matrix_sethsv(uint8_t h, uint8_t s, uint8_t v)` {#api-rgb-matrix-sethsv}
 
 Set the global effect hue, saturation, and value (brightness).

docs/features/rgblight.md

@@ -55,7 +55,7 @@ Changing the **Hue** cycles around the circle.<br>
 Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.<br>
 Changing the **Value** sets the overall brightness.<br>
 
-![QMK Color Wheel with HSV Values](https://i.imgur.com/vkYVo66.jpg)
+![QMK Color Wheel with HSV Values](/vkYVo66.jpg)
 
 ## Keycodes
 

docs/features/space_cadet.md

@@ -32,7 +32,7 @@ COMMAND_ENABLE = no
 
 ## Configuration
 
-By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifer`.
+By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifier` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifier`.
 
 |Define          |Default                        |Description                                                                      |
 |----------------|-------------------------------|---------------------------------------------------------------------------------|

docs/features/split_keyboard.md

@@ -91,11 +91,11 @@ SPLIT_TRANSPORT = custom
 
 Configuring your layout in a split keyboard works slightly differently to a non-split keyboard. Take for example the following layout. The top left numbers refer to the matrix row and column, and the bottom right are the order of the keys in the layout:
 
-![Physical layout](https://i.imgur.com/QeY6kMQ.png)
+![Physical layout](/QeY6kMQ.png)
 
 Since the matrix scanning procedure operates on entire rows, it first populates the left half's rows, then the right half's. Thus, the matrix as QMK views it has double the rows instead of double the columns:
 
-![Matrix](https://i.imgur.com/4wjJzBU.png)
+![Matrix](/4wjJzBU.png)
 
 ### Setting Handedness
 
@@ -249,7 +249,7 @@ Set to 0 to disable the disconnection check altogether.
 ```
 How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above).
 
-One communication attempt will be allowed everytime this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again.
+One communication attempt will be allowed every time this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again.
 
 Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size.
 
@@ -280,7 +280,7 @@ This enables syncing of the Host LED status (caps lock, num lock, etc) between b
 #define SPLIT_MODS_ENABLE
 ```
 
-This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen).
+This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifier state (e.g. displaying status on an OLED screen).
 
 ```c
 #define SPLIT_WPM_ENABLE
@@ -479,7 +479,7 @@ This set the maximum slave timeout when waiting for communication from master wh
 
 Master/slave delegation is made either by detecting voltage on VBUS connection or waiting for USB communication (`SPLIT_USB_DETECT`). Pro Micro boards can use VBUS detection out of the box and be used with or without `SPLIT_USB_DETECT`.
 
-Many ARM boards, but not all, do not support VBUS detection. Because it is common that ARM boards lack VBUS detection, `SPLIT_USB_DETECT` is automatically defined on ARM targets (technically when ChibiOS is targetted).
+Many ARM boards, but not all, do not support VBUS detection. Because it is common that ARM boards lack VBUS detection, `SPLIT_USB_DETECT` is automatically defined on ARM targets (technically when ChibiOS is targeted).
 
 ### Teensy boards
 
@@ -497,7 +497,7 @@ Once you have done that, you will want to solder the diode from the 5V pad to th
 
 You may need to use the 5V pad from the regulator block above as the pads were too small and placed too closely together to place the Schottky diode properly.
 
-![Teensy++ 2.0](https://i.imgur.com/BPEC5n5.png)
+![Teensy++ 2.0](/BPEC5n5.jpg)
 
 ## Additional Resources
 

docs/features/st7565.md

@@ -182,12 +182,12 @@ void st7565_render(void);
 void st7565_set_cursor(uint8_t col, uint8_t line);
 
 // Advances the cursor to the next page, writing ' ' if true
-// Wraps to the begining when out of bounds
+// Wraps to the beginning when out of bounds
 void st7565_advance_page(bool clearPageRemainder);
 
 // Moves the cursor forward 1 character length
 // Advance page if there is not enough room for the next character
-// Wraps to the begining when out of bounds
+// Wraps to the beginning when out of bounds
 void st7565_advance_char(void);
 
 // Writes a single character to the buffer at current cursor position

docs/features/stenography.md

@@ -4,6 +4,14 @@
 
 The [Open Steno Project](https://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
 
+## Steno Support in QMK
+
+There are three ways that QMK keyboards can support steno, with varying degrees of configuration required:
+
+1. Plover with [Arpeggiation](https://plover.wiki/index.php/Glossary#Arpeggiate) requires no changes to any keyboard and is supported by QMK as well as any other QWERTY keyboard.
+2. Plover with [NKRO](https://plover.wiki/index.php/Using_a_standard_keyboard_with_Plover#NKRO). If your keyboard supports NKRO in hardware and you have NKRO enabled as a USB endpoint, you can chord with the keyboard. Many devices will arrive stock like this and will require no changes.
+3. Steno Machine Protocols.  This requires the most configuration, but this has the advantage of allowing you to use your keyboard keys normally (either on another layer or another piece of hardware) without enabling and disabling your steno software.
+
 ## Plover with QWERTY Keyboard {#plover-with-qwerty-keyboard}
 
 Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
@@ -14,14 +22,14 @@ You may also need to adjust your layout, either in QMK or in Plover, if you have
 
 ## Plover with Steno Protocol {#plover-with-steno-protocol}
 
-Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
+Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `splitography/keymaps/default`.
 
 When QMK speaks to Plover over a steno protocol, Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover.
 
 In this mode, Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard.
 
 ::: info
-Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time.
+Due to hardware limitations, you might not be able to run both a virtual serial port and other features (mouse keys, NKRO, or MIDI support) at the same time. You will likely encounter a compile time error if this is the case. Disable those other features as necessary.
 :::
 
 ::: warning
@@ -94,7 +102,7 @@ STENO_ENABLE = yes
 STENO_PROTOCOL = all
 ```
 
-If you want to switch protocols programatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](../keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`.
+If you want to switch protocols programmatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](../keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`.
 
 The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard — assuming that your keyboard features (emulated) EEPROM.
 
@@ -156,7 +164,7 @@ At the end of this scenario given as an example, `chord` would have five bits se
 ## Keycode Reference {#keycode-reference}
 
 ::: info
-Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both.
+TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both.
 :::
 
 |GeminiPR|TX Bolt|Steno Key|

docs/features/tap_dance.md

@@ -40,6 +40,10 @@ Similar to the first option, the second and third option are good for simple lay
 
 For more complicated cases, like blink the LEDs, fiddle with the backlighting, and so on, use the fourth or fifth option. Examples of each are listed below.
 
+::: tip 
+If too many tap dances are active at the same time, later ones won't have any effect. You need to increase `TAP_DANCE_MAX_SIMULTANEOUS` by adding `#define TAP_DANCE_MAX_SIMULTANEOUS 5` (or higher) to your keymap's `config.h` file if you expect that users may hold down many tap dance keys simultaneously. By default, only 3 tap dance keys can be used together at the same time.
+:::
+
 ## Implementation Details {#implementation}
 
 Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works!
@@ -209,11 +213,13 @@ tap_dance_action_t tap_dance_actions[] = {
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
     tap_dance_action_t *action;
+    tap_dance_state_t* state;
 
     switch (keycode) {
-        case TD(CT_CLN): // list all tap dance keycodes with tap-hold configurations
+        case TD(CT_CLN):
-            action = &tap_dance_actions[QK_TAP_DANCE_GET_INDEX(keycode)];
+            action = tap_dance_get(QK_TAP_DANCE_GET_INDEX(keycode));
-            if (!record->event.pressed && action->state.count && !action->state.finished) {
+            state = tap_dance_get_state(QK_TAP_DANCE_GET_INDEX(keycode));
+            if (!record->event.pressed && state != NULL && state->count && !state->finished) {
                 tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data;
                 tap_code16(tap_hold->tap);
             }

docs/getting_started_github.md

@@ -8,15 +8,15 @@ This guide assumes you're somewhat comfortable with running things at the comman
 
 Start on the [QMK GitHub page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork":
 
-![Fork on GitHub](https://i.imgur.com/8Toomz4.jpg)
+![Fork on GitHub](/8Toomz4.jpg)
 
 If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
 
-![Download from GitHub](https://i.imgur.com/N1NYcSz.jpg)
+![Download from GitHub](/N1NYcSz.jpg)
 
 And be sure to select "HTTPS", and select the link and copy it:
 
-![HTTPS link](https://i.imgur.com/eGO0ohO.jpg)
+![HTTPS link](/eGO0ohO.jpg)
 
 From here, enter `git clone --recurse-submodules ` into the command line, and then paste your link:
 
@@ -57,10 +57,10 @@ To https://github.com/whoeveryouare/qmk_firmware.git
 
 Your changes now exist on your fork on GitHub - if you go back there (`https://github.com/<whoeveryouare>/qmk_firmware`), you can create a "New Pull Request" by clicking this button:
 
-![New Pull Request](https://i.imgur.com/DxMHpJ8.jpg)
+![New Pull Request](/DxMHpJ8.jpg)
 
 Here you'll be able to see exactly what you've committed - if it all looks good, you can finalize it by clicking "Create Pull Request":
 
-![Create Pull Request](https://i.imgur.com/Ojydlaj.jpg)
+![Create Pull Request](/Ojydlaj.jpg)
 
 After submitting, we may talk to you about your changes, ask that you make changes, and eventually accept it! Thanks for contributing to QMK :)

docs/getting_started_introduction.md

@@ -19,8 +19,8 @@ Within the folder `keyboards`, its subfolder `handwired` and its vendor and manu
 * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
 * `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support) for more information.
 * `readme.md`: A brief overview of the keyboard.
-* `<keyboardName>.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix.
+* `<keyboard>.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix.
-* `<keyboardName>.c`: This file is where you can find custom code for the keyboard.  
+* `<keyboard>.c`: This file is where you can find custom code for the keyboard.  
 
 For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines).
 

docs/getting_started_make_guide.md

@@ -1,8 +1,8 @@
 # More Detailed `make` Instructions
 
-The full syntax of the `make` command is `<keyboard_folder>:<keymap>:<target>`, where:
+The full syntax of the `make` command is `<keyboard>:<keymap>:<target>`, where:
 
-* `<keyboard_folder>` is the path of the keyboard, for example `planck`
+* `<keyboard>` is the path of the keyboard, for example `planck`
   * Use `all` to compile all keyboards
   * Specify the path to compile a revision, for example `planck/rev4` or `planck/rev3`
   * If the keyboard doesn't have any folders, it can be left out