more docs

docs/usecode-startup-override.md

@@ -53,6 +53,145 @@ The remaining uncertainty is narrower now:
 - whether it can also be a loader alias/resource root that `Filespec_GetFullPath` understands
 - whether relative, absolute, and CD-backed forms are all accepted equally
 
+What is now materially tighter from the live `Filespec_GetFullPath` and `File_Exists` implementations:
+
+- the path is interpreted with DOS file APIs, not Windows host-path APIs
+- the builder uses the literal separator string `"\\"`, not `"/"`
+- the parser-side `s_usecode` buffer is only `0x1e` bytes long, so the raw `-u` token is truncated to at most `29` visible characters plus the terminator
+
+That makes the safest current syntax guidance:
+
+- prefer DOS-style backslashes, not forward slashes
+- prefer short path tokens
+- assume the path must exist inside the game's DOS-visible filesystem view
+
+If the game is running under DOSBox or a similar DOS environment, `C:\MADDOCODE` refers to the guest DOS `C:` drive, not automatically to the Windows host `C:` drive.
+
+One more practical constraint is now strong enough to call out explicitly:
+
+- the `-u` existence probe uses an old DOS find-first style path, so `8.3`-safe directory names are the safest override roots
+
+For the current GOG install used in this investigation, Windows reports the short alias:
+
+- `MADDOCODE` -> `MADDOC~1`
+
+So the highest-probability next token for this specific setup is:
+
+- `-u MADDOC~1`
+
+or the explicit relative form:
+
+- `-u .\MADDOC~1`
+
+## Why `-u FLICTEST.FLX` Fails
+
+The live helper shape is now tight enough to explain the failed `FLICTEST` attempts directly.
+
+What retail `CRUSADER.EXE` does at `1420:0cf0..0d33` is:
+
+- read the copied argv token from `1478:065a`
+- load the fixed filename template through `1478:06d6/06d8 -> 1478:07a0`
+- use that template as `eusecode.flx`
+- call `Filespec_GetFullPath(0, <copied token>, "eusecode.flx", 0)`
+
+The raw data bytes at `1478:079a` confirm the fixed template directly:
+
+- `65 75 73 65 63 6f 64 65 2e 66 6c 78 00`
+- ASCII = `eusecode.flx\0`
+
+So these example invocations do **not** mean `load this exact archive file`:
+
+- `-u USECODE/FLICTEST.FLX`
+- `-u FLICTEST.FLX`
+
+They instead mean, in the current safest static interpretation:
+
+- use `USECODE/FLICTEST.FLX` as the `path` component and still append the fixed filename `eusecode.flx`
+- or use `FLICTEST.FLX` as the `path` component and still append the fixed filename `eusecode.flx`
+
+That makes both attempts wrong for a direct single-file override. The game is not being told to open your `FLICTEST.FLX` archive as the final filename at all.
+
+## Safest Current Experiment Shape
+
+The current safest static-model experiment is therefore:
+
+1. create a directory that will act as the override root
+2. place a structurally valid replacement archive in that directory
+3. name that archive `EUSECODE.FLX`
+4. pass the directory path to `-u`, not the archive filename
+
+Examples that now fit the recovered helper better are:
+
+- `-u USECODE`
+- `-u .\\USECODE`
+- `-u \USECODE`
+- `-u C:\USECODE`
+- `-u MOD_UC`
+
+with the important condition that the target directory must contain `EUSECODE.FLX`, not `FLICTEST.FLX`.
+
+The safest current path interpretations for those examples are:
+
+- `-u MADDOCODE` -> tries `MADDOCODE\EUSECODE.FLX` relative to the game's current DOS working directory
+- `-u .\MADDOCODE` -> tries `.\MADDOCODE\EUSECODE.FLX`
+- `-u \MADDOCODE` -> tries `\MADDOCODE\EUSECODE.FLX` on the current DOS drive
+- `-u C:\MADDOCODE` -> tries `C:\MADDOCODE\EUSECODE.FLX` on DOS drive `C:`
+
+The current safest negative guidance is:
+
+- do not use forward slashes like `USECODE/FLICTEST.FLX`
+- do not pass the archive filename itself as the `-u` token
+- do not assume a long absolute host path will survive the `0x1e`-byte parser buffer intact
+- do not assume a directory name longer than classic `8.3` DOS spelling will be accepted exactly as typed
+
+## Expected Visible Output
+
+There is currently no evidence that retail `-u` prints a success or failure banner before the game loads.
+
+What the live code shows:
+
+- the `-u` parser case at `1048:0a46` only copies the token into `1478:065a`
+- unlike `-debug`, `-warp`, `-skill`, `-mapoff`, `-egg`, and `-demo`, that parser case does **not** call `ConsolePrintf`
+- `startup_apply_u_override_if_present` also does not call `ConsolePrintf`
+- if `File_Exists` says the constructed path is missing, the helper just returns and startup continues
+
+So the safest current user-facing expectation is:
+
+- no dedicated `-u` console line on success
+- no dedicated `-u` console line on file-not-found failure
+- if the override path is wrong, the game most likely falls back silently to stock usecode
+
+That means `no message appeared before the game loaded` is currently normal and does **not** prove the override worked.
+
+## Strongest Current Diagnosis For The `MADDOCODE` Test Case
+
+The current install-side evidence makes this case much tighter than a generic `-u` experiment.
+
+What is now verified in the GOG install:
+
+- `MADDOCODE` contains `EUSECODE.FLX`, `OVERLOAD.DAT`, `UNKCOFF.DAT`, and `UNKDS.DAT`
+- `OVERLOAD.DAT`, `UNKCOFF.DAT`, and `UNKDS.DAT` in `MADDOCODE` are byte-identical to the working copies in `USECODE`
+- only `EUSECODE.FLX` differs between the stock `USECODE` folder and `MADDOCODE`
+
+That makes the A/B interpretation unusually clean.
+
+If:
+
+- replacing `USECODE\EUSECODE.FLX` with the hacked file produces the expected obvious gameplay breakage
+- but launching with `-u MADDOCODE` produces stock gameplay instead
+
+the strongest current read is **not** `the alternate root loaded but behaved differently`. The stronger current read is:
+
+- the alternate root was probably never selected
+- startup most likely fell back silently to stock usecode after the override path probe failed
+
+Given the recovered code and the current install layout, the leading practical failure mode is now:
+
+- the DOS-side file probe did not accept `MADDOCODE` exactly as typed
+- the short alias `MADDOC~1` is the next highest-probability working token
+
+This is still a static-analysis conclusion rather than a runtime-tested acceptance matrix, so the exact relative-path and alias forms remain open. But the filename side is no longer the main uncertainty: the recovered helper is strongly telling us `directory/root override for EUSECODE.FLX`, not `arbitrary filename override`.
+
 External engine code reinforces the fixed-filename part of this read. Both Pentagram and ScummVM build the default Crusader main usecode path as `usecode/` + language letter + `usecode.flx`, and for Remorse/Regret the language-usecode letter is `'e'`, which matches the retail helper's forced `eusecode.flx` template.
 
 ## Why This Looks Like Replacement, Not Addition
@@ -284,6 +423,8 @@ For current tooling planning, the defensive assumption should be:
 - prepare a structurally complete replacement source that satisfies the loader's normal expectations
 - do not assume the game will merge one partial class file into the stock runtime for us
 
+That also means a standalone archive like `FLICTEST.FLX` is currently a poor first experiment even if its internals are valid. The live retail loader path is much more likely to accept a complete replacement `EUSECODE.FLX` rooted under a directory passed to `-u`.
+
 ## Best Current Usefulness For Decompilation Work
 
 This path is interesting for the current usecode-decompilation lane for two reasons.