Add Naluluna mods and BSplus mods

2026-06-29 15:34:46 -07:00
parent 6117173507
commit 13d9481168
2 changed files with 234 additions and 26 deletions
@@ -103,7 +103,7 @@ Track the tool work discovered while using it for 1.44.1.
 | Model BSIPA/bootstrap installation separately | <span style="color:#8b949e; font-weight:600">todo</span> | BSManager creates root `IPA/`, `IPA.exe`, `winhttp.dll`, `Libs/`, `Logs`, `UserData`, and root `Plugins/`. |
 | Resolve BeatMods dependency closure | <span style="color:#8b949e; font-weight:600">todo</span> | Use as metadata/advisory input even when downloading plugin artifacts from upstream GitHub. |
 | Install BeatMods library payloads into `Libs/` | <span style="color:#8b949e; font-weight:600">todo</span> | Include framework-library cases when required; these are likely exceptions to GitHub-preferred sourcing. |
-| Support local/private plugin payloads | <span style="color:#8b949e; font-weight:600">todo</span> | Needed for paid closed-source and manual plugins. |
+| Support local/private plugin payloads | <span style="color:#8b949e; font-weight:600">todo</span> | Needed for paid closed-source and manual plugins. BeatSaberPlus 6.4.5 was installed manually from a Discord-only release zip on 2026-06-29. |
 | Record install state for every copied file | <span style="color:#8b949e; font-weight:600">todo</span> | Required for rollback and clean omission testing. |
 | Add a batch install workflow or documented command sequence | <span style="color:#8b949e; font-weight:600">todo</span> | Useful for two-or-three-at-a-time validation. |
 | Add IPA log inspection helper | <span style="color:#8b949e; font-weight:600">todo</span> | Nice-to-have; manual log watching via `docs/SMOKETEST.md` is acceptable today. |
@@ -222,33 +222,37 @@ Purpose: add visual and stream-facing mods after functional mods are stable.
 Purpose: restore private plugin set only after public/dependency-heavy mods are
 known good.

+See `docs/notes/naluluna-mod-assistant.md` for how NalulunaModAssistant sources
+Patreon-only Naluluna packages, where it installs them by default, and how to
+treat its output as local/private payload input for `plugin-helper`.
+
 | Plugin | Upstream | Status | Source/version | Verification notes |
 | --- | --- | --- | --- | --- |
 | ReeSabers |  | <span style="color:#8b949e; font-weight:600">todo</span> | paid/private | Verify saber visuals in VR when practical. |
-| BeatSaberPlus_Chat |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup and module UI. |
-| BeatSaberPlus_ChatEmoteRain |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_ChatIntegrations |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_ChatRequest |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_GameTweaker |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_MenuMusic |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_Multiplayer |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_NoteTweaker |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_SongChartVisualizer |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| BeatSaberPlus_SongOverlay |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| NalulunaMenu |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup and menu. |
-| NalulunaCounters |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify in-song counters. |
-| NalulunaLevelDetail |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify song detail panel. |
-| NalulunaSliceVisualizer |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify in-song visuals. |
-| NalulunaSongPreview |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify song preview. |
-| NalulunaMissIndicator |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify in-song visuals. |
-| NalulunaEnergy |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify in-song HUD. |
-| NalulunaFps |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify overlay. |
-| NalulunaPPCoin |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| NalulunaRewinder |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify startup. |
-| NalulunaAvatars |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify avatar load. |
-| NalulunaShaders |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify dependency for Naluluna visuals. |
-| NalulunaSkybox |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify skybox sample manifest and skybox load. |
-| NalulunaUtils |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Verify dependency load. |
+| BeatSaberPlus_Chat | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Discord release zip `BeatSaberPlus_v6.4.5-bs-1.44.0.zip`, SHA-256 `21ad51edea5703485779b851e7e86aac11c3d6e3b1de2460b2c3c3b4b5704657`; manual install into Windows BSManager `1.44.1` root `Plugins/` | IPA loaded BeatSaberPlus_Chat 6.4.5, ChatPlexSDK initialized all modules and added a menu button, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.44.0. Chat/Twitch module UI not exercised in FPFC smoke. |
+| BeatSaberPlus_ChatEmoteRain | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_ChatEmoteRain 6.4.5 and ChatPlexSDK initialized the Chat Emote Rain module; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_ChatIntegrations | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_ChatIntegrations 6.4.5 and ChatPlexSDK initialized the Chat Integrations module; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_ChatRequest | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_ChatRequest 6.4.5 and ChatPlexSDK initialized the Chat Request module; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_GameTweaker | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_GameTweaker 6.4.5 and applied Harmony patches; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_MenuMusic | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_MenuMusic 6.4.5 and applied Harmony patches; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_Multiplayer | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_Multiplayer 6.4.5, applied Harmony patches, and added a menu button; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_NoteTweaker | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_NoteTweaker 6.4.5 and applied Harmony patches; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_SongChartVisualizer | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_SongChartVisualizer 6.4.5 and ChatPlexSDK initialized the Song Chart Visualizer module; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| BeatSaberPlus_SongOverlay | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Same Discord bundle as BeatSaberPlus_Chat | IPA loaded BeatSaberPlus_SongOverlay 6.4.5 and ChatPlexSDK initialized the Song Overlay module; same FPFC smoketest as BeatSaberPlus_Chat on 2026-06-29. |
+| NalulunaMenu | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaMenu` 1.2.0 archive `NalulunaMenu-1.2.0-bs1.44.1.zip`; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaMenu 1.2.0, logged `Init`, `OnMenu`, `PlayDefaultMenuMusic`, and registered its menu button; the game reached `MainSystemInit`. Warning: IPA logged missing `NalulunaMenu.resources`. |
+| NalulunaCounters | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaCounters` 1.3.2; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaCounters 1.3.2, logged `BeatLeader: available`, initialized its menu button, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.43.0. In-song counters not exercised in FPFC smoke. |
+| NalulunaLevelDetail | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaLevelDetail` 2.0.0; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaLevelDetail 2.0.0, controller `Awake`, menu button registration, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.39.1. Song detail panel not exercised in FPFC smoke. |
+| NalulunaSliceVisualizer |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Not present in Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29. Verify in-song visuals after install. |
+| NalulunaSongPreview | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaSongPreview` 1.0.1; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaSongPreview 1.0.1, controller `Awake`, menu button registration, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.40.4. Song preview not exercised in FPFC smoke. |
+| NalulunaMissIndicator |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Not present in Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29. Verify in-song visuals after install. |
+| NalulunaEnergy | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaEnergy` 1.1.0; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaEnergy 1.1.0, controller `Awake`, menu button registration, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.42.0. In-song HUD not exercised in FPFC smoke. |
+| NalulunaFps |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Not present in Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29. Verify overlay after install. |
+| NalulunaPPCoin |  | <span style="color:#8b949e; font-weight:600">todo</span> | local/private | Not present in Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29. Verify startup after install. |
+| NalulunaRewinder | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaRewinder` 1.2.0; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaRewinder 1.2.0, config loaded, menu button registered, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.42.2. Rewind behavior not exercised in FPFC smoke. |
+| NalulunaAvatars | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaAvatars` 1.10.0 plus bundled `AliciaSolid` 1.10.0 manifest; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaAvatars 1.10.0, logged `Init`, started OSC face tracking, and registered its menu button; the game reached `MainSystemInit`. Warnings: configured avatar `2299336039803240.vrm` missing; IPA logged missing `NalulunaAvatars.resources`; one `NullReferenceException` in `HMUI.CurvedCanvasSettings.Start` during menu setup. VR avatar load not exercised. |
+| NalulunaShaders | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaShaders` 2.1.3 archive `NalulunaShaders-2.1.3-bs1.39.1.zip`; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaShaders 2.1.3, logged `Assets loaded`, and the game reached `MainSystemInit`. Warning: manifest targets Beat Saber 1.39.1. |
+| NalulunaSkybox | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaSkybox` 2.0.0 plus `NalulunaSkyboxSamples` 1.1.0 manifest; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaSkybox 2.0.0 and NalulunaSkyboxSamples 1.1.0, controller `Awake`, menu button registration, and the game reached `MainSystemInit`. Warning: Skybox manifest targets Beat Saber 1.39.1. Skybox swap not exercised in FPFC smoke. |
+| NalulunaUtils | [patreon](https://www.patreon.com/c/naluluna/posts) | <span style="color:#d29922; font-weight:600">verified with warning</span> | Patreon via NalulunaModAssistant; `NalulunaUtils` 5.7.0 archive `NalulunaUtils-5.7.0-bs1.44.0.zip` plus bundled `OpenVRHelper` 0.2.3 manifest; manual install into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded NalulunaUtils 5.7.0 and OpenVRHelper 0.2.3, logged `Awake`, registered dependent Naluluna menu buttons, and `OnMenuSceneActive: Succeeded`; the game reached `MainSystemInit`. Warnings: manifest targets Beat Saber 1.44.0; IPA logged missing `NalulunaUtils.resources` and optional libs (SteamVR, DynamicBone, FinalIK, CameraPlus, BGNet). |

 ## Shared Libraries and Dependency Packages

@@ -268,6 +272,7 @@ are user-facing features.
 | SongDetailsCache | [github](https://github.com/kinsi55/BeatSaber_SongDetails) | <span style="color:#d29922; font-weight:600">verified with warning</span> | BetterSongList, SongRankedBadge | GitHub `kinsi55/BeatSaber_SongDetails` tag `v1.4.0`, asset `SongDetailsCache.BS.Lib.zip`; BeatMods version id 2226, zipHash `e1167b64cd3eff7e3651ec2dbbe50d81` | IPA loaded SongDetailsCache 1.4.0 and SongRankedBadge used it to load song details. Warning: manifest targets Beat Saber 1.13.2. |
 | System.IO.Compression | [beatmods zip](https://beatmods.com/cdn/mod/a4e9e26f61967e56168e08eecb01ab88.zip) | <span style="color:#d29922; font-weight:600">verified with warning</span> | BeatSaberPlaylistsLib, System.IO.Compression.FileSystem | BeatMods 4.6.57, version id 1763, zipHash `a4e9e26f61967e56168e08eecb01ab88` | IPA loaded System.IO.Compression 4.6.57; logged a duplicate-library notice because the game also ships this assembly. |
 | System.IO.Compression.FileSystem | [beatmods zip](https://beatmods.com/cdn/mod/e19f6fd395d54de7bfcbbbe3084dea28.zip) | <span style="color:#3fb950; font-weight:600">verified</span> | BeatSaverDownloader | BeatMods 4.7.3056, version id 1762, zipHash `e19f6fd395d54de7bfcbbbe3084dea28` | IPA loaded System.IO.Compression.FileSystem 4.7.3056. |
+| ChatPlexSDK_BS | [discord](https://discord.com/channels/723117082111246416/768683248804167690) | <span style="color:#d29922; font-weight:600">verified with warning</span> | BeatSaberPlus | Bundled in Discord release zip `BeatSaberPlus_v6.4.5-bs-1.44.0.zip`; manually installed into Windows BSManager `1.44.1` root `Plugins/` on 2026-06-29 | IPA loaded ChatPlexSDK_BS 6.4.5, initialized all BeatSaberPlus modules, added a menu button, and cached Twitch/BTTV/FFZ/7TV emotes during FPFC smoke on 2026-06-29. Warning: manifest targets Beat Saber 1.44.0. |
 | Dynamic Bone |  | <span style="color:#dbab79; font-weight:600">defer</span> | TBD | TBD | Include only if a selected 1.44.1 mod requires it. |
 | Final IK |  | <span style="color:#dbab79; font-weight:600">defer</span> | TBD | TBD | Include only if a selected 1.44.1 mod requires it. |

@@ -296,4 +301,4 @@ Record plugins skipped for this 1.44.1 pass. This is not a fix list for today.
 | 5 | | <span style="color:#8b949e; font-weight:600">todo</span> | | |
 | 6 | | <span style="color:#8b949e; font-weight:600">todo</span> | | |
 | 7 | 2026-06-29 | <span style="color:#d29922; font-weight:600">verified with warning</span> | Installed and smoke-tested AdBlocker 1.0.5, HighlightBombs 1.0.3, PitchBlack 0.0.3, and ReeCamera 0.0.5. All four loaded and the game reached `MainSystemInit`. HighlightBombs installed its app installer and loaded QuickOutline material. ReeCamera logged Spout load success and installed app/menu installers. | Warnings: all four manifests target older Beat Saber versions (1.34.2, 1.32.0, 1.39.1, 1.42.0). AdBlocker and PitchBlack used BeatMods CDN or byte-identical GitHub assets because JonnyVR1/AdBlocker exposes no GitHub releases and HighlightBombs BeatMods 1.0.3 is newer than GitHub v1.0.1. ReeCamera first launch logged missing `UserData/ReeCamera.json` until mod creates it on exit; archive replaced bundled `CameraUtils.dll`. In-song bomb/lighting/camera visuals were not exercised in FPFC smoke. Pre-existing LeaderboardCore and PlaylistManager errors still appear in the log. |
-| 8 | | <span style="color:#8b949e; font-weight:600">todo</span> | | |
+| 8 | 2026-06-29 | <span style="color:#d29922; font-weight:600">verified with warning</span> | FPFC smoketest `Logs/2026.06.29.15.32.05.log`: BeatSaberPlus 6.4.5 bundle and ChatPlexSDK_BS loaded and initialized all modules; ten Patreon Naluluna packages loaded (`NalulunaUtils`, `NalulunaMenu`, `NalulunaAvatars`, `NalulunaSkybox`, `NalulunaShaders`, `NalulunaCounters`, `NalulunaEnergy`, `NalulunaLevelDetail`, `NalulunaSongPreview`, `NalulunaRewinder`); NalulunaUtils registered menu buttons and `OnMenuSceneActive: Succeeded`; NalulunaMenu played default menu music; the game reached `MainSystemInit`. | Warnings: BeatSaberPlus/ChatPlex and several Naluluna manifests target older Beat Saber versions; NalulunaUtils logged missing satellite resources and optional libs; NalulunaAvatars referenced a missing configured VRM and hit one menu `NullReferenceException`; pre-existing LeaderboardCore Harmony patch error still appears; slice/miss/fps/ppcoin Naluluna mods remain uninstalled; in-song Naluluna features and VR avatar load were not exercised. |
@@ -0,0 +1,203 @@
+# NalulunaModAssistant Source and Install Notes
+
+This note records how NalulunaModAssistant behaves when used to install
+Patreon-only Naluluna mods. It is intended to guide future `plugin-helper`
+support for private/local payloads without checking private artifacts,
+session-specific URLs, or account data into the repo.
+
+Observed run:
+
+- Date: 2026-06-29
+- Assistant path: `C:\Users\pleb\Apps\Naluluna\NalulunaModAssistant.exe`
+- Assistant version: `1.5.1`
+- Runtime UI: WebView2 `149.0.4022.80`
+- Log path: `C:\Users\pleb\Apps\Naluluna\Logs\NalulunaModAssistant\_latest.log`
+
+## High-Level Flow
+
+NalulunaModAssistant is a WebView2 desktop app. It authenticates the user through
+an embedded browser, fetches a versioned mod catalog, then downloads selected
+plugin archives into a temporary working directory before extracting them into
+the configured Beat Saber directory.
+
+The observed Patreon flow was:
+
+1. Initialize WebView2 and a temporary working directory.
+2. Load the initial catalog JSON named `start`.
+3. Navigate to Patreon at `https://www.patreon.com/c/naluluna/posts`.
+4. Resolve the NalulunaModAssistant files post:
+   `https://www.patreon.com/naluluna/posts/nalulunamodassis-74489236`.
+5. Confirm the logged-in Patreon account has access.
+6. Detect Beat Saber version `1.44.1`.
+7. Select mod list version `1.42.0`.
+8. Fetch the catalog JSON named `1-42-0`.
+9. Download selected archives and extract their payloads into the configured
+   Beat Saber tree.
+
+The assistant binary also contains a `GetJsonFromGoogleSiteAsync` code path and
+Fanbox login/status paths. Those appear to be alternate or older source flows.
+The 2026-06-29 run used Patreon, not Google Sites, GitHub, BeatMods, or Fanbox.
+
+## Source Model
+
+Naluluna plugin artifacts are not normal public GitHub or BeatMods releases.
+For Patreon installs, the authoritative source is the private
+NalulunaModAssistant Patreon post and its attachment metadata.
+
+The assistant downloads files through two forms:
+
+- Relative catalog paths such as `nma/files/NalulunaUtils-5.7.0-bs1.44.0.zip`
+  and `nma/imgs/NalulunaCounters.jpg`.
+- Patreon file endpoints such as `https://www.patreon.com/file?...`, which
+  resolve to tokenized `patreonusercontent.com` CDN URLs after authentication.
+
+Do not record tokenized CDN URLs, cookies, WebView profile data, or private
+account identifiers in repo files. They are session-specific and may grant access
+to paid artifacts. For lockfile-style notes, record the Patreon post, the
+assistant-visible archive name, the mod version, the Beat Saber target string,
+the installed paths, and local file hashes when available.
+
+## Catalog Versioning
+
+In the observed run, the game was `1.44.1` but the assistant selected
+`modListVersion: 1.42.0` and fetched catalog node `1-42-0`.
+
+That means the assistant's catalog version should not be assumed to exactly
+match the game version. Treat it as an upstream compatibility bucket. For
+documentation and locks, record both values:
+
+- actual game version reported by the assistant
+- mod list version selected by the assistant
+
+## Install Target
+
+The assistant reads and writes a configured Beat Saber directory, not a
+BSManager instance root chosen by `plugin-helper`.
+
+Observed config:
+
+- Beat Saber directory:
+  `C:\Program Files (x86)\Steam\steamapps\common\Beat Saber`
+- Working directory:
+  `C:\Users\pleb\AppData\Local\Temp\tmp97E.tmp`
+
+This matters because the observed run installed into the Steam Beat Saber tree,
+not the BSManager `1.44.1` instance at
+`C:\Users\pleb\BSManager\BSInstances\1.44.1`.
+
+Before using NalulunaModAssistant as a source for a BSManager instance, either:
+
+- point the assistant at the intended BSManager instance root, if the UI allows
+  it, or
+- treat the Steam install as a staging source and copy exact installed files into
+  the target instance through a `plugin-helper` local/private payload workflow.
+
+Do not manually copy files into the live instance as a substitute for
+`plugin-helper` state tracking unless this is an explicit one-off recovery step.
+
+## Extraction Behavior
+
+Archives are extracted relative to the Beat Saber directory. The observed
+payloads wrote to these top-level areas:
+
+- `Plugins/`
+- `Libs/Native/`
+- `UserData/NalulunaUtils/`
+- `UserData/NalulunaSkybox/`
+- `NalulunaAvatars/`
+
+Examples from the observed run:
+
+- `Plugins/NalulunaUtils.dll`
+- `Plugins/NalulunaAvatars.dll`
+- `Plugins/NalulunaSkybox.dll`
+- `Plugins/NalulunaSkyboxSamples.manifest`
+- `Libs/Native/OVRLipSync.dll`
+- `UserData/NalulunaUtils/OpenVRHelper/OpenVRHelper.exe`
+- `UserData/NalulunaSkybox/*.jpgx`
+- `NalulunaAvatars/AliciaSolid.vrm`
+
+Some packages install manifests or data assets instead of a plugin DLL. A
+`plugin-helper` implementation should record every extracted file, not just the
+primary DLL.
+
+## Observed Install Batch
+
+The 2026-06-29 run installed the following selected packages:
+
+- `NalulunaShaders` `2.1.3`, archive
+  `NalulunaShaders-2.1.3-bs1.39.1.zip`
+- `NalulunaUtils` `5.7.0`, archive
+  `NalulunaUtils-5.7.0-bs1.44.0.zip`
+- `AliciaSolid` `1.10.0`, archive
+  `AliciaSolid-1.10.0-bs1.26.0.zip`
+- `NalulunaAvatars` `1.10.0`
+- `NalulunaSkybox` `2.0.0`
+- `OpenVRHelper` `0.2.3`
+- `NalulunaRewinder` `1.2.0`
+- `NalulunaCounters` `1.3.2`
+- `NalulunaEnergy` `1.1.0`
+- `NalulunaLevelDetail` `2.0.0`
+- `NalulunaSongPreview` `1.0.1`
+- `NalulunaSkyboxSamples` `1.1.0`
+
+The first `NalulunaUtils` attempt downloaded successfully but failed extraction
+with a Windows file-lock error:
+
+```text
+The process cannot access the file
+'C:\Users\pleb\AppData\Local\Temp\tmp97E.tmp\NalulunaUtils-5.7.0-bs1.44.0.zip'
+because it is being used by another process.
+```
+
+A later retry succeeded and extracted `Plugins/NalulunaUtils.dll`.
+
+Several downloads log `download interrupted: FileSecurityCheckFailed` after a
+successful install. In the observed run, those messages did not necessarily mean
+the mod failed; the assistant logged `Installed: ...` first. Treat this message
+as a warning to cross-check against extracted files and the assistant's final
+success/failure count.
+
+## Implications for plugin-helper
+
+Private Naluluna payloads should be modeled as local/private artifacts rather
+than first-class remote fetches until there is an explicit supported way to
+authenticate and download them safely.
+
+Recommended near-term workflow:
+
+1. Use NalulunaModAssistant to download/install into a staging Beat Saber tree.
+2. Inspect the assistant log for selected package names, versions, archive names,
+   and extracted paths.
+3. Hash the installed files or preserved archives.
+4. Add a `plugin-helper` local/private payload entry for each package.
+5. Apply that payload to the intended BSManager instance with normal install
+   state recording.
+6. Smoketest the BSManager instance and record results in
+   `docs/notes/install-and-verify-plugins-1.44.1.md`.
+
+Longer term, `plugin-helper` could add a "local archive import" command that
+accepts a zip from the assistant's working directory or a saved local cache,
+normalizes the extracted paths, computes hashes, and creates an auditable
+install plan without needing to understand Patreon authentication.
+
+## What Not To Commit
+
+Do not commit:
+
+- downloaded private plugin archives
+- tokenized `patreonusercontent.com` URLs
+- WebView2 profile data
+- Patreon or Fanbox cookies
+- full `_patreon.log` / `_fanbox.log` captures
+- account identifiers from logs
+
+Safe to commit:
+
+- assistant version
+- Patreon post URL
+- package names and versions
+- non-tokenized archive names shown by the assistant
+- extracted relative paths
+- hashes of local artifacts or installed files
+- compatibility and smoketest notes