diff --git a/PROJECT-BRIEF.md b/PROJECT-BRIEF.md index e364b0f..36e1716 100644 --- a/PROJECT-BRIEF.md +++ b/PROJECT-BRIEF.md @@ -130,6 +130,49 @@ Two channels, different jobs. **Use [A] to verify what [B] did.** Full operational detail, version pins, and the failure decoder: **`CLAUDE.md`**. +#### Rojo must run natively on Windows — never over an SSH tunnel + +**Rojo runs on the Windows box, in the Windows checkout.** Studio, Rojo and the +repo it serves all live on the same machine. Start it with: + +```cmd +cd /d %USERPROFILE%\roblox\tokyo-wangan-racing +%USERPROFILE%\.local\bin\rojo.exe serve default.project.json --port 34872 +``` + +A scheduled task `RojoTWR` does exactly this — `schtasks /Run /TN "RojoTWR"`. +(Launching via `start` over SSH does **not** work: the process dies when the SSH +session exits. Use the task.) + +> ⚠️ **Do not reverse-tunnel a Linux Rojo to port 34872.** It was tried +> (`ssh -N -R 34872:127.0.0.1:34872`) and it is actively harmful: the port +> answers, `/api/rojo` returns valid JSON, and everything *looks* healthy — but +> it is serving the **Linux** working tree. Studio then syncs files that are not +> the ones being edited on Windows, and `netstat` shows the port owned by +> **sshd** rather than `rojo`. If port 34872 is owned by anything other than a +> process literally named `rojo`, that is the bug. +> +> Diagnostic that settles it in one line: +> ```powershell +> $l=(netstat -ano | Select-String ":34872.*LISTENING"); (Get-Process -Id (($l[0] -split "\s+")[-1])).ProcessName +> ``` +> Expect `rojo`. If you get `sshd`, kill the tunnel. + +#### `ServerPackages` is gitignored — Rojo will not start without it + +`/Packages/`, `/ServerPackages/` and `wally.lock` are **gitignored**, so a fresh +clone has no dependencies and Rojo **refuses to start**, exiting immediately: + +``` +[ERROR rojo] Rojo project referred to a file using $path that could not be +turned into a Roblox Instance by Rojo. File $path: ServerPackages +``` + +That error means *missing Wally deps*, not a broken project file. There is only +one dependency (`ProfileStore`, 19 files / 316 KB). Fix with `wally install`, or +copy the folder from a machine that already has it. **Rojo exiting on startup is +silent from Studio's side — it just looks like Rojo "won't connect."** + ### 4b. Reference material on the NAS (1.5 GB, verified present) Host `unraid-1` (10.10.10.43), reachable over SSH. Base path: