chore: add Codex project context and agent guidance

.agents/skills/kst4contest-change/references/architecture.md

@@ -0,0 +1,102 @@
+# Architecture context
+
+## Current package shape
+
+The repository currently contains major packages under `src/main/java/kst4contest/` including:
+
+- `controller`
+- `locatorUtils`
+- `logic`
+- `model`
+- `service`
+- `test`
+- `utils`
+- `view`
+
+Do not treat package names alone as proof of clean MVC boundaries. Inspect actual dependencies.
+
+## Preferred message/member data flow
+
+The established target architecture for active chat members is:
+
+```text
+ON4KST / network
+        |
+        v
+MessageBusManagementThread
+        |
+        v
+ChatController
+        |
+        v
+thread-safe active-member domain state
+(ConcurrentMap; identity includes callsign + category)
+        |
+        v
+JavaFX ObservableList UI mirror
+        |
+        v
+FilteredList / SortedList / TableView / selection
+```
+
+Key rule:
+
+`ObservableList` is a JavaFX UI projection, not the canonical store for worker-thread logic.
+
+`MessageBusManagementThread` must not directly read or modify the UI list.
+
+## JavaFX boundary
+
+UI-visible mutations belong on the JavaFX Application Thread.
+
+Prefer controller-owned helpers such as an existing `runOnFxThread` abstraction when available; otherwise use `Platform.runLater` consistently.
+
+Do not move business/data access into the FX thread merely to silence a threading problem.
+
+## Parser/service separation
+
+For protocol receivers, the preferred direction is:
+
+```text
+Receiver (I/O only)
+    -> Parser (wire data -> DTO)
+    -> Service (domain/persistence logic)
+    -> Controller (UI coordination)
+    -> Observable UI model
+    -> View
+```
+
+A previous concrete example for UCXLog was:
+
+```text
+UcxUdpReceiver
+    -> UcxPacketParser
+    -> DTO
+    -> UcxLogService
+    -> ChatController
+    -> UI projection
+```
+
+This is architectural guidance, not permission for a broad refactor. Apply only when it is in scope and approved.
+
+## DTO preference
+
+Prefer explicit DTO classes over records when introducing protocol/transport data structures in this project, unless the approved concept intentionally changes that convention.
+
+## Null safety
+
+Chat members can be incomplete, especially:
+
+- fallback members;
+- historic message senders;
+- server-derived partial members.
+
+Values such as QRB and QTF can be absent.
+
+Rules:
+
+- absence stays absence;
+- do not map `null` to numeric zero;
+- UI must render unavailable state safely;
+- sorting/filtering/calculation code must tolerate missing values;
+- unexpected missing values must not terminate worker or UI threads.