Initial public release of rem-essentials

docs/architecture.md

@@ -0,0 +1,43 @@
+# Architecture
+
+`rem-essentials` is intentionally feature-first. Every migrated behavior should
+live in its own module and be registered as a named feature in `src/main.cpp`.
+
+## Feature registration
+
+Each feature has:
+
+- a stable config key
+- an init function
+- an optional cleanup function
+- a runtime side: `Client`, `Server`, or `Always`
+- a code default
+
+The INI file can override each default. Missing INI entries keep the compiled
+default.
+
+## Current feature keys
+
+The full key list lives in `rem-essentials.ini`. Feature switches live in
+`[rem-essentials]`; typed parameters used by the graphics, saves, and
+screenshots behavior live in the `[flplusplus]` section.
+
+## Design rules
+
+- Prefer one feature flag per behavior, even when multiple behaviors share one
+  option.
+- Keep client and server hooks in separate files.
+- Resolve optional Freelancer imports at runtime when practical.
+- Keep adapted third-party code isolated under `third_party/` and wrap it with
+  thin REM adapters instead of adding a second plugin entry point.
+
+## Proton-sensitive fixes
+
+Mouse features stay split because Wine/Proton can handle cursor APIs
+differently from native Windows. The current conservative defaults are:
+
+- `cursor_visibility_fix = true`
+- `cursor_border_flicker_fix = false`
+- `mouse_warp_fix = false`
+
+These can be enabled per player in `rem-essentials.ini` after testing.