From 4ba5e92248a0d48c0d763447dd2334b23362ba8d Mon Sep 17 00:00:00 2001
From: Cabbagec <root@everdream.xyz>
Date: Sun, 26 Jul 2026 04:34:08 +0000
Subject: [PATCH] fix: map x2 route override by folder path

---
 deploy/production/README.md      | 6 ++++--
 deploy/production/x2/client.toml | 2 +-
 docs/deployment-and-usage.md     | 5 +++--
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/deploy/production/README.md b/deploy/production/README.md
index 1c4cb19..7ad0b4d 100644
--- a/deploy/production/README.md
+++ b/deploy/production/README.md
@@ -35,13 +35,15 @@ volumes:
 [syncthing]
 api_root = "/var/syncthing"
 local_root = "/data/sync"
-local_path_overrides = { "/var/syncthing/DownloadsSync-X2" = "/data/qb/Sync" }
+local_path_overrides = { "/var/syncthing/Downloads/Sync" = "/data/qb/Sync" }
 ```
 
 Do **not** additionally mount `/srv/downloads/Sync` at a path beneath
 `/data/sync`. The override is the authoritative mapping for that folder and
 keeps qB source files and staging destinations in one mount namespace. Use
-the folder ID returned by Syncthing's configuration as the override key.
+the folder's normalized API-visible **path** as the override key (for example,
+Syncthing `~/Downloads/Sync` becomes `/var/syncthing/Downloads/Sync`); do not
+use the folder ID.
 
 Before starting a stack, validate it with:
 
diff --git a/deploy/production/x2/client.toml b/deploy/production/x2/client.toml
index 00f5e9e..e1eee49 100644
--- a/deploy/production/x2/client.toml
+++ b/deploy/production/x2/client.toml
@@ -42,5 +42,5 @@ local_root = "/data/sync"
 # `DownloadsSync-X2` is ~/Downloads/Sync on the host, nested below the qB
 # root. Resolve it through /data/qb rather than a second nested bind mount so
 # source staging can hardlink it.
-local_path_overrides = { "/var/syncthing/DownloadsSync-X2" = "/data/qb/Sync" }
+local_path_overrides = { "/var/syncthing/Downloads/Sync" = "/data/qb/Sync" }
 advertised_addresses = ["dynamic"]
diff --git a/docs/deployment-and-usage.md b/docs/deployment-and-usage.md
index 24e2608..80ace49 100644
--- a/docs/deployment-and-usage.md
+++ b/docs/deployment-and-usage.md
@@ -131,8 +131,9 @@ the same client bind mount. This enables hardlinks without creating two Docker
 mount boundaries for the same host files. Do not add a second bind mount for
 the nested folder: Linux treats it as a distinct mount even when it has the
 same `st_dev`, and the client correctly falls back to copy-only capacity
-accounting. See the production deployment README for the required compose and
-override pattern.
+accounting. The override key is the normalized Syncthing folder path beneath
+`api_root`, not its folder ID. See the production deployment README for the
+required compose and override pattern.
 
 The remaining node examples omit optional `[connection]`, `[jobs]`, and
 `[backup]` tables and therefore use these same defaults; deployments may