From 7afdf764f09daa5d0d05befd52750984d01c1baf Mon Sep 17 00:00:00 2001
From: Bryan Ramos <bryan@ramos.codes>
Date: Mon, 9 Mar 2026 00:40:36 -0400
Subject: [PATCH] Add submodule workflow documentation

---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 45 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 12d1907..9b3c336 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,48 @@ Invoke `just` in order to view an available list of project scripts
 
 `user.configs.nix` is a symlink to conveniently access centrally defined common user variables from the repo root
 
-⚠️ Be sure to tailor any hardware settings to your own  
-⚠️ Replace the `hardware.nix` found in the `src/system/machines/<machine>` directory  
-⚠️ Run `nixos-generate-config` to generate a `hardware-configuration.nix` for your current system  
+⚠️ Be sure to tailor any hardware settings to your own
+⚠️ Replace the `hardware.nix` found in the `src/system/machines/<machine>` directory
+⚠️ Run `nixos-generate-config` to generate a `hardware-configuration.nix` for your current system
+
+## Submodules
+
+This repo uses git submodules for portable configurations.
+
+### Neovim Config
+The Neovim configuration is a separate repo for portability across non-NixOS systems.
+
+**Location:** `src/user/modules/utils/modules/neovim/config/nvim`
+**Repo:** [github.com/itme-brain/nvim](https://github.com/itme-brain/nvim)
+
+#### Cloning with submodules
+```bash
+git clone --recurse-submodules git@github.com:itme-brain/nixos.git
+# Or after cloning:
+git submodule update --init
+```
+
+#### Updating nvim config
+```bash
+# Edit files in the submodule, then:
+cd src/user/modules/utils/modules/neovim/config/nvim
+git add . && git commit -m "your changes" && git push
+
+# Update reference in nixos repo:
+cd ~/nixos
+git add src/user/modules/utils/modules/neovim/config/nvim
+git commit -m "Update nvim submodule" && git push
+```
+
+#### Pulling nvim updates from remote
+```bash
+cd ~/nixos
+git submodule update --remote
+git add src/user/modules/utils/modules/neovim/config/nvim
+git commit -m "Update nvim submodule" && git push
+```
+
+#### Standalone nvim install (non-NixOS)
+```bash
+git clone git@github.com:itme-brain/nvim.git ~/.config/nvim
+```