diff --git a/.github/workflows/build_binaries.yaml b/.github/workflows/build_binaries.yaml
index f53c3c81..67103f27 100755
--- a/.github/workflows/build_binaries.yaml
+++ b/.github/workflows/build_binaries.yaml
@@ -9,9 +9,8 @@ jobs:
   build:
     name: 'QMK Userspace Build'
     uses: qmk/.github/.github/workflows/qmk_userspace_build.yml@main
-    with:
-      qmk_repo: Keebart/vial-qmk-corne-choc-pro
-      qmk_ref: vial
+    # Firmware lives in qmk_firmware/ submodule — no external repo needed.
+    # The reusable workflow detects the submodule and skips its own clone.
 
   publish:
     name: 'QMK Userspace Publish'
diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 00000000..00746970
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,4 @@
+[submodule "qmk_firmware"]
+	path = qmk_firmware
+	url = https://github.com/Keebart/vial-qmk-corne-choc-pro.git
+	branch = vial
diff --git a/README.md b/README.md
index 55a38834..3f54f715 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,71 @@
 # QMK Userspace — Keebart Corne Choc Pro
 
-## Setup
+Self-contained repo: firmware (Keebart's QMK fork) is embedded as a submodule at `qmk_firmware/`.
+No waiting on upstream — cherry-pick, merge, or patch anything you want right here.
 
-1. Use [qmk/qmk_userspace](https://github.com/qmk/qmk_userspace) as a template to create your repo
-2. Clone your new repo
-3. Unzip this into it
-4. Add the Keebart fork as a submodule:
+## Quick start
 
 ```bash
-git submodule add https://github.com/Keebart/vial-qmk-corne-choc-pro.git qmk_firmware
-git submodule update --init --recursive
+git clone --recursive https://github.com/timfee/qmk_userspace.git
+cd qmk_userspace
 ```
 
-5. Commit and push:
+GitHub Actions builds the `.uf2` automatically on push — download from the **Releases** tab.
+
+Flash: hold **Q** while plugging in the left half, drag `.uf2` onto `RPI-RP2`. Repeat with **P** for the right half.
+
+## Local builds
 
 ```bash
-git add .
-git commit -m "Initial keymap"
-git push
+pip install qmk
+qmk setup -H qmk_firmware   # point QMK at the submodule
+qmk compile -kb keebart/corne_choc_pro/standard -km timfee
 ```
 
-6. GitHub Actions builds the .uf2 — download from the Releases tab
-7. Flash: hold Q while plugging in left half, drag .uf2 onto RPI-RP2. Repeat with P for right.
+## Pulling upstream changes
+
+The submodule tracks the `vial` branch of `Keebart/vial-qmk-corne-choc-pro`.
+
+```bash
+# Pull latest from Keebart
+cd qmk_firmware
+git fetch origin
+git merge origin/vial        # or: git rebase origin/vial
+cd ..
+git add qmk_firmware
+git commit -m "Update firmware submodule"
+```
+
+### Cherry-picking from other repos (e.g. Keebart/vial-qmk-keebart, qmk/qmk_firmware)
+
+```bash
+cd qmk_firmware
+
+# Add any upstream remote once
+git remote add upstream-qmk https://github.com/qmk/qmk_firmware.git
+git remote add keebart-full https://github.com/Keebart/vial-qmk-keebart.git
+
+# Fetch and cherry-pick
+git fetch keebart-full
+git cherry-pick <commit-sha>   # e.g. OLED SSD1312 support
+
+cd ..
+git add qmk_firmware
+git commit -m "Cherry-pick: <description>"
+```
+
+### Switching to your own firmware fork
+
+If you fork `Keebart/vial-qmk-corne-choc-pro` to your own GitHub account:
+
+```bash
+cd qmk_firmware
+git remote set-url origin https://github.com/YOUR_USER/vial-qmk-corne-choc-pro.git
+git push origin vial          # push your changes to your fork
+cd ..
+# Update .gitmodules to point at your fork
+git config -f .gitmodules submodule.qmk_firmware.url \
+  https://github.com/YOUR_USER/vial-qmk-corne-choc-pro.git
+git add .gitmodules qmk_firmware
+git commit -m "Point submodule at my firmware fork"
+```
diff --git a/qmk_firmware b/qmk_firmware
new file mode 160000
index 00000000..4649f864
--- /dev/null
+++ b/qmk_firmware
@@ -0,0 +1 @@
+Subproject commit 4649f864f15ba9f540ee83d66b50cb9fcd4f7e59