sky-bro · Aug 11, 2026 · Aug 10, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,6 +1,19 @@
-name: Build ZMK firmware
-on: [push, pull_request, workflow_dispatch]
+name: Build firmware
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
   build:
-    uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@cb615aee9a7c427e251f2ab62080c1a44a165da9
+    # The module-owned workflow applies its version-matched ZMK compatibility
+    # patch before building. Pinning it keeps the module and build procedure in sync.
+    uses: nxtkb/zmk-feature-codex-micro/.github/workflows/build-user-config.yml@034050c6cac7834b5004aad510863e7c999f6307
+    with:
+      build_matrix_path: build.yaml
+      archive_name: sweep-pro-firmware
diff --git a/build.yaml b/build.yaml
@@ -9,11 +9,11 @@
 include:
 - board: nice_nano//zmk
   shield: sweep_left
-  snippet: studio-rpc-usb-uart
+  snippet: studio-rpc-usb-uart nxtkb-codex-micro-usb nxtkb-codex-micro-ble
   artifact-name: sweep_left
 - board: nice_nano//zmk
   shield: sweep_left sweep_left_display_hw sweep_display
-  snippet: studio-rpc-usb-uart
+  snippet: studio-rpc-usb-uart nxtkb-codex-micro-usb nxtkb-codex-micro-ble
   artifact-name: sweep_left_display
 - board: nice_nano//zmk
   shield: sweep_right

diff --git a/config/sweep.keymap b/config/sweep.keymap
@@ -10,6 +10,10 @@
 #include <dt-bindings/zmk/keys.h>
 #include <dt-bindings/zmk/outputs.h>
 #include <dt-bindings/zmk/pointing.h>
+#if defined(NXTKB_CODEX_MICRO)
+#include <dt-bindings/nxtkb/codex.h>
+#include <behaviors/codex_key.dtsi>
+#endif
 
 #include "behaviors/character_map.dtsi"
 #include "behaviors/report.dtsi"
@@ -21,6 +25,17 @@
 #define LEF 3
 #define TRI 4
 #define MOUSE 5
+#define CODEX 6
+
+#if defined(NXTKB_CODEX_MICRO)
+#define CODEX_ENTRY &tog CODEX
+#define CODEX_EXIT &tog CODEX
+#define CODEX_KEY(n) &codex_key n
+#else
+#define CODEX_ENTRY &trans
+#define CODEX_EXIT &trans
+#define CODEX_KEY(n) &trans
+#endif
 
 #define SPEED_POINTER 0
 #define SPEED_SCROLL 1
@@ -33,7 +48,6 @@
 #define CIRQUE_MODE_ABSOLUTE 1
 #define CIRQUE_MODE_TOGGLE 2
 
-
 &sensors {
 	left_encoder {
 		triggers-per-rotation = <15>;
@@ -251,7 +265,7 @@
 		tri_layer {
 			display-name = "FUN";
 			bindings = <
-			&kp F1  &kp F2   &kp F3   &kp F4   &bt BT_SEL 0    &bt BT_SEL 2  &out OUT_TOG   &tog WIN  &kp C_MUTE    &kp C_PREV
+			&kp F1  &kp F2   &kp F3   &kp F4   &bt BT_SEL 0    &bt BT_SEL 2  &out OUT_TOG   CODEX_ENTRY  &kp C_MUTE    &kp C_PREV
 			&kp F5  &kp F6   &kp F7   &kp F8   &bt BT_SEL 1    &bt BT_SEL 3  &kp C_BRI_UP   &studio_unlock    &kp C_VOL_UP  &kp C_PP
 			&kp F9  &kp F10  &kp F11  &kp F12  &bt BT_CLR      &bt BT_SEL 4  &kp C_BRI_DEC  &soft_off     &kp C_VOL_DN  &kp C_NEXT
 			&kp C_MUTE  &trans   &trans          &trans        &trans  &studio_unlock
@@ -269,5 +283,18 @@
 			>;
 			sensor-bindings = <&enc_ptr_spd &enc_scrl_spd>;
 		};
+
+#if defined(NXTKB_CODEX_MICRO)
+		codex {
+			display-name = "CODEX";
+			bindings = <
+			CODEX_KEY(CODEX_AGENT_0)  CODEX_KEY(CODEX_AGENT_1)  CODEX_KEY(CODEX_AGENT_2)  CODEX_KEY(CODEX_AGENT_3)  CODEX_KEY(CODEX_AGENT_4)  CODEX_KEY(CODEX_AGENT_5)  &trans  &trans  &trans  CODEX_EXIT
+			CODEX_KEY(CODEX_APPROVE)  CODEX_KEY(CODEX_SPLIT)  CODEX_KEY(CODEX_DECLINE)  CODEX_KEY(CODEX_FAST)  &trans  CODEX_KEY(CODEX_MIC)  CODEX_KEY(CODEX_SEND)  &trans  &trans  &trans
+			&trans  &trans  &trans         &trans         &trans           &trans         &trans         &trans         &trans  &trans
+			&trans  &trans  &trans         &trans         &trans           &studio_unlock
+			>;
+			sensor-bindings = <&inc_dec_kp C_VOL_DN C_VOL_UP &inc_dec_kp C_BRI_DEC C_BRI_UP>;
+		};
+#endif
 	};
 };
diff --git a/config/west.yml b/config/west.yml
@@ -13,7 +13,10 @@ manifest:
     import: app/west.yml
   - name: zmk-vfx-sweep-pro-display
     remote: nxtkb
-    revision: 88809b0ba9f8af51e937c90d3c34edb9480e5455
+    revision: afae3dcf7d94113dfbeb19fb4e4fbd08d6564008
+  - name: zmk-feature-codex-micro
+    remote: nxtkb
+    revision: 034050c6cac7834b5004aad510863e7c999f6307
   - name: zmk-behavior-report
     remote: nxtkb
     revision: 476f43da1f98b4a6150c9c0e499a257bd64a29a0

diff --git a/docs/en/local-build.md b/docs/en/local-build.md
@@ -30,11 +30,18 @@ Install the Zephyr SDK from AUR, or install it manually by following the ZMK/Zep
 paru -S zephyr-sdk
 ```
 
-If the SDK is not detected automatically, set these variables in the current shell:
+On Apple Silicon macOS, install the host tools with Homebrew and install the Zephyr SDK version
+required by the ZMK revision pinned in `config/west.yml` (currently 0.17.0):
+
+```shell
+brew install cmake ninja ccache dtc wget xz protobuf
+```
+
+If the SDK is not detected automatically, point Zephyr at your installation in the current shell:
 
 ```shell
 export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
-export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-0.17.0"
+export ZEPHYR_SDK_INSTALL_DIR="/path/to/zephyr-sdk-0.17.0"
 ```
 
 ## Initialize Python
@@ -158,6 +165,59 @@ west build -d build/sweep_right_trackpad
 
 If you change the shield, extra modules, snippets, or `ZMK_CONFIG`, rerun the full command with `-p` to regenerate the build directory.
 
+## Codex Micro USB and Bluetooth build
+
+This build adds a second vendor-defined USB HID interface and an encrypted vendor-defined
+HID-over-GATT report while preserving the normal ZMK USB/Bluetooth HID and Studio USB UART
+interfaces. Codex RPC follows ZMK's selected output endpoint, including the active Bluetooth
+profile. Inactive USB and Bluetooth hosts cannot take over the Codex session by retrying.
+
+The repository's default GitHub Actions workflow builds Codex-enabled central firmware and applies
+the required official-ZMK compatibility patch automatically. For a local checkout in which the
+Codex module is a west project, apply the same declared patch once before building:
+
+```shell
+west patch -sm zmk-feature-codex-micro apply
+```
+
+If the module is instead a sibling directory outside the west workspace, apply its patch to ZMK
+once with `git apply`, then add the module to the local module list:
+
+```shell
+git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply --check \
+    "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch"
+git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply \
+    "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch"
+CODEX_EXTRA_MODULES="$EXTRA_MODULES;$NXTKB_ROOT/zmk-feature-codex-micro"
+```
+
+Build the left half with display and both Codex transports:
+
+```shell
+west build -s app -p -d build/sweep_left_display_codex -b nice_nano//zmk \
+    -S studio-rpc-usb-uart \
+    -S nxtkb-codex-micro-usb \
+    -S nxtkb-codex-micro-ble -- \
+    -DSHIELD="sweep_left sweep_left_display_hw sweep_display" \
+    -DZMK_EXTRA_MODULES="$CODEX_EXTRA_MODULES" \
+    -DZMK_CONFIG="$ZMK_CONFIG_DIR"
+```
+
+NXTKB development checkouts may also contain a gitignored
+`nxtkb-codex-micro-lab-identity` snippet for local interoperability testing against the current
+ChatGPT desktop detection. It changes both the USB VID/PID and Bluetooth Device Information
+identity and is intentionally not part of the module repository. Never publish or ship firmware
+built with that identity. External integrations must use an identity they are authorized to ship.
+The right half continues to use the normal `sweep_right` or `sweep_right_trackpad` firmware.
+
+After first flashing a BLE-enabled build, forget the old keyboard in the host Bluetooth settings,
+clear the selected ZMK Bluetooth profile, and pair with `NXTKB Codex Lab` again. HID report maps are
+cached in the bond. Use the existing output-toggle key to prefer Bluetooth; a connected USB cable
+may still be used for charging. USB and Bluetooth keyboard connections remain active instead of
+disconnecting each other. Every connected computer keeps an independent Codex protocol and Agent
+state session; Codex keys and the display follow only the currently selected ZMK output. Switching
+back restores the last Agent state reported by that computer.
+
 ## Troubleshooting
 
 If you see:

diff --git a/docs/zh_CN/local-build.md b/docs/zh_CN/local-build.md
@@ -30,11 +30,18 @@ Zephyr SDK 可以通过 AUR 安装，或按 ZMK/Zephyr 官方文档手动安装
 paru -S zephyr-sdk
 ```
 
-如果 SDK 没有被自动识别，可以在当前 shell 里指定：
+macOS（Apple Silicon）建议使用 Homebrew 安装宿主工具，并安装 `config/west.yml` 中固定的
+ZMK revision 所要求的 Zephyr SDK 版本（当前为 0.17.0）：
+
+```shell
+brew install cmake ninja ccache dtc wget xz protobuf
+```
+
+如果 SDK 没有被自动识别，请在当前 shell 里指向你自己的安装目录：
 
 ```shell
 export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
-export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-0.17.0"
+export ZEPHYR_SDK_INSTALL_DIR="/path/to/zephyr-sdk-0.17.0"
 ```
 
 ## 初始化 Python 环境
@@ -158,6 +165,56 @@ west build -d build/sweep_right_trackpad
 
 修改了 shield、extra modules、snippets 或 `ZMK_CONFIG` 后，建议继续使用带 `-p` 的完整命令重新生成构建目录。
 
+## Codex Micro USB 与蓝牙构建
+
+该构建会增加第二个 vendor-defined USB HID interface，以及加密的 vendor-defined
+HID-over-GATT report，同时保留 ZMK 普通 USB/蓝牙 HID 和 Studio USB UART。Codex RPC
+响应发起请求的传输通道。
+
+仓库的默认 GitHub Actions workflow 会构建启用 Codex 的 central 固件，并自动应用所需的
+官方 ZMK 兼容补丁。本地构建时，如果 Codex 模块是 west workspace 中的 project，请先
+应用模块声明的补丁：
+
+```shell
+west patch -sm zmk-feature-codex-micro apply
+```
+
+如果模块位于 west workspace 外部的同级目录，则先用 `git apply` 向 ZMK 应用一次补丁，
+再把 Codex 模块加入本地模块列表：
+
+```shell
+git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply --check \
+    "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch"
+git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply \
+    "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch"
+CODEX_EXTRA_MODULES="$EXTRA_MODULES;$NXTKB_ROOT/zmk-feature-codex-micro"
+```
+
+编译同时支持 USB 和蓝牙 Codex 通道的左手墨水屏固件：
+
+```shell
+west build -s app -p -d build/sweep_left_display_codex -b nice_nano//zmk \
+    -S studio-rpc-usb-uart \
+    -S nxtkb-codex-micro-usb \
+    -S nxtkb-codex-micro-ble -- \
+    -DSHIELD="sweep_left sweep_left_display_hw sweep_display" \
+    -DZMK_EXTRA_MODULES="$CODEX_EXTRA_MODULES" \
+    -DZMK_CONFIG="$ZMK_CONFIG_DIR"
+```
+
+NXTKB 的开发 checkout 中可能还会包含一个被 gitignore 排除的
+`nxtkb-codex-micro-lab-identity` snippet，仅用于本地测试当前 ChatGPT 桌面端的发现行为。
+它会同时修改 USB VID/PID 和蓝牙 Device Information identity，且有意不放入模块仓库；
+禁止发布或交付使用该身份生成的固件。外部集成必须使用自己有权发布的设备身份。右手继续
+使用原有 `sweep_right` 或 `sweep_right_trackpad` 固件。
+
+首次刷入带 BLE 支持的固件后，需要先在主机蓝牙设置中忽略旧键盘、清除所选 ZMK
+蓝牙 profile，再重新配对 `NXTKB Codex Lab`。HID report map 会被缓存在旧 bond 中，普通
+断开重连不会刷新。使用现有的 output toggle 键切换到蓝牙优先；USB 线仍可保留用于充电。
+USB 和蓝牙键盘连接不会互斥或彼此断开。每个连接的电脑维持独立的 Codex 协议与 Agent
+状态；Codex 按键和墨水屏状态只跟随当前 ZMK output。切换回来后会恢复该电脑最后上报的
+Agent 状态。
+
 ## 常见问题
 
 如果看到：