diff --git a/docs/guide.md b/docs/guide.md
index f3c16c2..2a7349c 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -165,6 +165,34 @@ SUBREPO_SSH_KEY="-----BEGIN OPENSSH PRIVATE KEY-----
 # AUTH_REPO_TOKEN=<auth-specific-token>
 ```
 
+### Updating josh-sync in devenv
+
+To update to the latest version:
+
+```bash
+devenv update josh-sync
+```
+
+Or with plain Nix flakes:
+
+```bash
+nix flake lock --update-input josh-sync
+```
+
+To pin to a specific version, use a tag ref in `devenv.yaml`:
+
+```yaml
+josh-sync:
+  url: git+https://your-gitea.example.com/org/josh-sync?ref=v1.1
+  flake: true
+```
+
+After updating, verify the version:
+
+```bash
+josh-sync --version
+```
+
 ### Option B: Manual installation
 
 Install the required tools, then either: