Document asset cache roadmap

docs/ROADMAP.md

@@ -23,6 +23,39 @@ installations even when they share an instance name. Lockfiles can stay keyed by
 Beat Saber version, but bootstrap state, generated plans, backups, and
 `installed.json` need to stay target-specific.
 
+Asset downloads are currently colocated with target-specific state under the
+same state root. That is convenient for the first CLI slice, but it makes
+dual-boot use awkward: pointing Linux at the Windows state root reuses the asset
+downloads, but also reuses the Windows `installed.json`. A later state layout
+should separate a reusable asset cache from per-install managed state, for
+example:
+
+```text
+cache/
+  downloads/<beat-saber-version>/<plugin-id>/<asset>
+
+instances/
+  <install-id>/
+    installed.json
+    bootstrap.json
+    plans/
+    backups/
+```
+
+There is no urgent need to migrate the layout before the rest of the helper
+settles, but new code should avoid assuming that downloads and per-install
+state must always live together.
+
+The version lock should eventually include structured source URLs for every
+asset so the helper can fetch missing downloads itself. The lock already pins
+the selected repo, tag, asset name, and checksum; adding source fields would
+make the fetch path explicit for both GitHub release assets and BeatMods CDN
+fallbacks. Hashes should remain useful audit metadata and a warning signal, but
+the UX needs a recovery path for replaced upstream assets: report the mismatch,
+show the expected and actual hashes, and let the user intentionally refresh or
+re-lock after inspection instead of treating every mismatch as an unrecoverable
+dead end.
+
 ## Future: Nix-Orchestrated Plugin Sets
 
 Once Beat Saber is running on Linux through Steam Proton, it may make sense to let Nix orchestrate the plugin payload itself.