update: update Dedicated Server developer guide

English is machine translated.
Please forgive me.

Minecraft.Server/docs/DEVELOPMENT.en.md

@@ -7,20 +7,23 @@ This document is for contributors who are new to `Minecraft.Server` and need a p
 `Minecraft.Server` is the dedicated-server executable entry for this codebase.
 
 Core responsibilities:
-- Read and normalize `server.properties`
-- Initialize Windows/network/runtime systems
-- Load or create the target world
-- Run the dedicated main loop (network tick, XUI actions, autosave, CLI command processing)
-- Perform safe save and shutdown
+- Switch the process working directory to the executable folder before relative file I/O
+- Load, normalize, and repair `server.properties`
+- Initialize dedicated runtime systems, connection logging, and access control
+- Load or create the target world and keep `level-id` aligned with the actual save destination
+- Run the dedicated main loop (network tick, XUI actions, autosave, CLI input)
+- Maintain operator-facing access files such as `banned-players.json` and `banned-ips.json`
+- Perform an initial save for newly created worlds and then shut down safely
 
 ## 2. Important Files
 
 ### Startup and Runtime
 - `Windows64/ServerMain.cpp`
-  - Process entry (`main`)
-  - CLI argument parsing
+  - `PrintUsage()` and `ParseCommandLine()`
+  - `SetExeWorkingDirectory()`
   - Runtime setup and shutdown flow
-  - Main loop + autosave scheduler
+  - Initial save path for newly created worlds
+  - Main loop, autosave scheduler, and CLI polling
 
 ### World Selection and Save Load
 - `WorldManager.h`
@@ -32,21 +35,41 @@ Core responsibilities:
 ### Server Properties
 - `ServerProperties.h`
 - `ServerProperties.cpp`
-  - Default values
-  - Parse/normalize/write `server.properties`
+  - Default values and normalization ranges
+  - Parse/repair/write `server.properties`
   - Exposes `ServerPropertiesConfig`
+  - `SaveServerPropertiesConfig()` rewrites `level-name`, `level-id`, and `white-list`
 
-### Logging
+### Access Control, Ban, and Whitelist Storage
+- `Access/Access.h`
+- `Access/Access.cpp`
+  - Process-wide access-control facade
+  - Published snapshot model used by console commands and login checks
+- `Access/BanManager.h`
+- `Access/BanManager.cpp`
+  - Reads/writes `banned-players.json` and `banned-ips.json`
+  - Normalizes identifiers and filters expired entries from snapshots
+- `Access/WhitelistManager.h`
+- `Access/WhitelistManager.cpp`
+  - Reads/writes `whitelist.json`
+  - Normalizes XUID-based whitelist entries used by login validation and CLI commands
+
+### Logging and Connection Audit
 - `ServerLogger.h`
 - `ServerLogger.cpp`
   - Log level parsing
   - Colored/timestamped console logs
-  - Standard categories (`startup`, `world-io`, `console`, etc.)
+  - General categories such as `startup`, `world-io`, `console`, `access`, `network`, and `shutdown`
+- `ServerLogManager.h`
+- `ServerLogManager.cpp`
+  - Accepted/rejected TCP connection logs
+  - Login/disconnect audit logs
+  - Remote-IP cache used by `ban-ip <player>`
 
 ### Console Command System
 - `Console/ServerCli.cpp` (facade)
 - `Console/ServerCliInput.cpp` (linenoise input thread + completion bridge)
-- `Console/ServerCliParser.cpp` (tokenization/quoted args/completion context)
+- `Console/ServerCliParser.cpp` (tokenization, quoted args, completion context)
 - `Console/ServerCliEngine.cpp` (dispatch, completion, helpers)
 - `Console/ServerCliRegistry.cpp` (command registration + lookup)
 - `Console/commands/*` (individual commands)
@@ -54,25 +77,72 @@ Core responsibilities:
 ## 3. End-to-End Startup Flow
 
 Main flow in `Windows64/ServerMain.cpp`:
-1. Load `server.properties` via `LoadServerPropertiesConfig()`
-2. Apply CLI argument overrides (`-port`, `-bind`, `-name`, `-seed`, `-loglevel`)
-3. Initialize runtime systems (window/device/profile/network/thread storage)
-4. Set host/game options from `ServerPropertiesConfig`
-5. Bootstrap world with `BootstrapWorldForServer(...)`
-6. Start hosted game thread (`RunNetworkGameThreadProc`)
-7. Enter main loop:
+1. `SetExeWorkingDirectory()` switches the current directory to the executable folder.
+2. Load and normalize `server.properties` via `LoadServerPropertiesConfig()`.
+3. Copy config into `DedicatedServerConfig`, then apply CLI overrides (`-port`, `-ip`/`-bind`, `-name`, `-maxplayers`, `-seed`, `-loglevel`, `-help`/`--help`/`-h`).
+4. Initialize process state, `ServerLogManager`, and `Access::Initialize(".")`.
+5. Initialize window/device/profile/network/thread-local systems.
+6. Set host/game options from `ServerPropertiesConfig`.
+7. Bootstrap world with `BootstrapWorldForServer(...)`.
+8. If world bootstrap resolves a different normalized save ID, persist it with `SaveServerPropertiesConfig()`.
+9. Start hosted game thread (`RunNetworkGameThreadProc`).
+10. If a brand-new world was created, explicitly request one initial save.
+11. Enter the main loop:
    - `TickCoreSystems()`
    - `HandleXuiActions()`
    - `serverCli.Poll()`
    - autosave scheduling
-8. On shutdown:
-   - wait for action idle
-   - request final save
-   - halt server and terminate network/device subsystems
+12. On shutdown:
+   - stop CLI input
+   - request save-on-exit / halt server
+   - wait for network shutdown completion
+   - terminate log, access, network, and device systems
 
-## 4. Common Development Tasks
+## 4. Current Operator Surface
 
-### 4.1 Add a New CLI Command
+### 4.1 Launch Arguments
+- `-port <1-65535>`
+- `-ip <addr>` or `-bind <addr>`
+- `-name <name>` (runtime max 16 chars)
+- `-maxplayers <1-8>`
+- `-seed <int64>`
+- `-loglevel <debug|info|warn|error>`
+- `-help`, `--help`, `-h`
+
+Notes:
+- CLI overrides affect only the current process.
+- The only values currently written back by the server are `level-name` and `level-id`, and that happens when world bootstrap resolves identity changes.
+
+### 4.2 Built-in Console Commands
+- `help` / `?`
+- `stop`
+- `list`
+- `ban <player> [reason ...]`
+  - currently requires the target player to be online
+- `ban-ip <address|player> [reason ...]`
+  - accepts a literal IPv4/IPv6 address or an online player's current remote IP
+- `pardon <player>`
+- `pardon-ip <address>`
+  - only accepts a literal address
+- `banlist`
+- `tp <player> <target>` / `teleport`
+- `gamemode <survival|creative|0|1> [player]` / `gm`
+
+CLI behavior notes:
+- Command parsing accepts both `cmd` and `/cmd`.
+- Quoted arguments are supported by `ServerCliParser`.
+- Completion is implemented per command via `Complete(...)`.
+
+### 4.3 Files Written Next to the Executable
+- `server.properties`
+- `banned-players.json`
+- `banned-ips.json`
+
+This follows from `SetExeWorkingDirectory()`, so these files are resolved relative to `Minecraft.Server.exe`, not the shell directory you launched from.
+
+## 5. Common Development Tasks
+
+### 5.1 Add a New CLI Command
 
 Use this pattern when adding commands like `/kick`, `/time`, etc.
 
@@ -81,65 +151,97 @@ Use this pattern when adding commands like `/kick`, `/time`, etc.
    - `CliCommandYourCommand.cpp`
 2. Implement `IServerCliCommand`
    - `Name()`, `Usage()`, `Description()`, `Execute(...)`
-   - Optional: `Aliases()` and `Complete(...)`
-3. Register command in `ServerCliEngine::RegisterDefaultCommands()`
+   - optional: `Aliases()` and `Complete(...)`
+3. Register the command in `ServerCliEngine::RegisterDefaultCommands()`.
 4. Add source/header to build definitions:
    - `CMakeLists.txt` (`MINECRAFT_SERVER_SOURCES`)
    - `Minecraft.Server/Minecraft.Server.vcxproj` (`<ClCompile>` / `<ClInclude>`)
 5. Manual verify:
    - command appears in `help`
    - command executes correctly
-   - completion behavior is correct for both `cmd` and `/cmd`
+   - completion works for both `cmd` and `/cmd`
+   - quoted arguments behave as expected
 
 Implementation references:
-- `CliCommandHelp.cpp` for simple no-arg command
+- `CliCommandHelp.cpp` for a simple no-arg command
 - `CliCommandTp.cpp` for multi-arg + completion + runtime checks
-- `CliCommandGamemode.cpp` for argument parsing and mode validation
+- `CliCommandGamemode.cpp` for argument parsing and aliases
+- `CliCommandBanIp.cpp` for access-backed behavior with connection metadata
 
-### 4.2 Add or Change a `server.properties` Key
+### 5.2 Add or Change a `server.properties` Key
 
-1. Add/update field in `ServerPropertiesConfig` (`ServerProperties.h`)
-2. Add default value to `kServerPropertyDefaults` (`ServerProperties.cpp`)
-3. Load and normalize value in `LoadServerPropertiesConfig()`
-   - Use existing read helpers for bool/int/string/int64/log level
-4. If this value should be persisted on save, update `SaveServerPropertiesConfig()`
-5. Apply to runtime where needed:
+1. Add/update the field in `ServerPropertiesConfig` (`ServerProperties.h`).
+2. Add a default entry to `kServerPropertyDefaults` (`ServerProperties.cpp`).
+3. Load and normalize the value in `LoadServerPropertiesConfig()`.
+   - Use existing helpers for bool/int/string/int64/log level/level type.
+4. If this value should be written back, update `SaveServerPropertiesConfig()`.
+   - Note: today that function intentionally only persists world identity.
+5. Apply it to runtime where needed:
    - `ApplyServerPropertiesToDedicatedConfig(...)`
    - host options in `ServerMain.cpp` (`app.SetGameHostOption(...)`)
+   - `PrintUsage()` / `ParseCommandLine()` if the key also gets a CLI override
 6. Manual verify:
-   - file regeneration when key is missing
-   - invalid values are normalized
+   - missing key regeneration
+   - invalid value normalization
+   - clamped ranges still make sense
    - runtime behavior reflects the new value
 
-### 4.3 Change World Load/Create Behavior
+Normalization details worth remembering:
+- `level-id` is normalized to a safe save ID and length-limited.
+- `server-name` is capped to 16 runtime chars.
+- `max-players` is clamped to `1..8`.
+- `autosave-interval` is clamped to `5..3600`.
+- `level-type` normalizes to `default` or `flat`.
+
+### 5.3 Change Ban / Access Behavior
+
+Primary code lives in `Access/Access.cpp`, `Access/BanManager.cpp`, and `ServerLogManager.cpp`.
+
+When changing this area:
+- Keep `BanManager` responsible for storage/caching, not live-network policy.
+- Keep the clone-and-publish snapshot pattern in `Access.cpp` so readers never block on disk I/O.
+- Remember that `ban-ip <player>` depends on `ServerLogManager::TryGetConnectionRemoteIp(...)`.
+- Keep expired entries out of `SnapshotBannedPlayers()` / `SnapshotBannedIps()` output.
+- Verify:
+  - clean boot creates empty ban files when missing
+  - `ban`, `ban-ip`, `pardon`, `pardon-ip`, and `banlist` still work
+  - online bans disconnect live targets immediately
+  - manual edits still reload safely if you later add or extend reload paths
+
+### 5.4 Change World Load/Create Behavior
 
 Primary code is in `WorldManager.cpp`.
 
 Current matching policy:
-1. Match by `level-id` (`UTF8SaveFilename`) first
-2. Fallback to world-name match on title/file name
+1. Match by `level-id` (`UTF8SaveFilename`) first.
+2. Fall back to world-name match on title/file name.
 
 When changing this logic:
-- Keep `ApplyWorldStorageTarget(...)` usage consistent (title + save ID together)
-- Preserve periodic ticking in wait loops (`tickProc`) to avoid async deadlocks
-- Keep timeout/error logs specific enough for diagnosis
+- Keep `ApplyWorldStorageTarget(...)` usage consistent (title + save ID together).
+- Preserve periodic ticking in wait loops (`tickProc`) to avoid async deadlocks.
+- Keep timeout/error logs specific enough for diagnosis.
 - Verify:
   - existing world is reused correctly
   - no accidental new save directory creation
   - shutdown save still succeeds
+  - newly created worlds still get the explicit initial save from `ServerMain.cpp`
 
-### 4.4 Add Logging for New Feature Work
+### 5.5 Add Logging for New Feature Work
 
 Use `ServerLogger` helpers:
 - `LogDebug`, `LogInfo`, `LogWarn`, `LogError`
-- or formatted variants `LogInfof`, etc.
+- formatted variants `LogDebugf`, `LogInfof`, etc.
+
+Use `ServerLogManager` when the event is specifically part of the transport/login/disconnect lifecycle.
 
 Recommended categories:
 - `startup` for init/shutdown lifecycle
 - `world-io` for save/world operations
 - `console` for CLI command handling
+- `access` for ban/access control state
+- `network` for connection/login audit
 
-## 5. Build and Run
+## 6. Build and Run
 
 From repository root:
 
@@ -147,30 +249,36 @@ From repository root:
 cmake -S . -B build -G "Visual Studio 17 2022" -A x64
 cmake --build build --config Debug --target MinecraftServer
 cd .\build\Debug
-.\Minecraft.Server.exe -port 25565 -bind 0.0.0.0 -name DedicatedServer
+.\Minecraft.Server.exe -port 25565 -bind 0.0.0.0 -maxplayers 8 -name DedicatedServer
 ```
 
 Notes:
-- Launch from output directory so relative assets/files resolve correctly
-- `server.properties` is loaded from current working directory
-- For Visual Studio workflow, see root `COMPILE.md`
+- The process switches its working directory to the executable directory at startup.
+- `server.properties`, `banned-players.json`, and `banned-ips.json` are therefore read/written next to the executable.
+- For Visual Studio workflow, see root `COMPILE.md`.
 
-## 6. Safety Checklist Before Commit
+## 7. Safety Checklist Before Commit
 
-- The server starts without crash on a clean `server.properties`
-- Existing world loads by expected `level-id`
-- New world creation path still performs initial save
-- CLI still accepts input and completion is responsive
-- No busy wait path removed from async wait loops
-- Both CMake and `.vcxproj` include newly added source files
+- the server starts without crash when `server.properties` is missing or sparse
+- missing access files are recreated on a clean boot
+- existing world loads by expected `level-id`
+- new world creation still performs the explicit initial save
+- CLI input and completion remain responsive
+- `banlist` output stays sane after adding/removing bans
+- no busy-wait path removed from async wait loops
+- both CMake and `.vcxproj` include newly added source files
 
-## 7. Quick Troubleshooting
+## 8. Quick Troubleshooting
 
-- Unknown command not found:
+- Unknown command:
   - check `RegisterDefaultCommands()` and build-file entries
+- `server.properties` or ban files seem to load from the wrong folder:
+  - remember `SetExeWorkingDirectory()` moves the working directory to the executable folder
 - Autosave or shutdown save timing out:
   - confirm wait loops still call `TickCoreSystems()` and `HandleXuiActions()` where required
 - World not reused on restart:
   - inspect `level-id` normalization and matching logic in `WorldManager.cpp`
+- `ban-ip <player>` cannot resolve an address:
+  - confirm the player is currently online and `ServerLogManager` has a cached remote IP for that connection
 - Settings not applied:
-  - confirm value is loaded into `ServerPropertiesConfig` and then applied in `ServerMain.cpp`
+  - confirm the value is loaded into `ServerPropertiesConfig`, optionally copied into `DedicatedServerConfig`, and then applied in `ServerMain.cpp`

Minecraft.Server/docs/DEVELOPMENT.ja.md

@@ -1,51 +1,74 @@
 # Minecraft.Server 開発ガイド (日本語)
 
-このドキュメントは、`Minecraft.Server` の内部構成を知らない人でも、機能追加や修正を安全に進められるようにまとめた実践ガイドです。
+この文書は、`Minecraft.Server` に新しく入る開発者が、安全に機能追加や改修を行うための実践的な地図として使うことを想定しています
 
-## 1. Minecraft.Server の役割
+## 1. このサーバーが担うこと
 
-`Minecraft.Server` は本リポジトリの Dedicated Server 実行エントリです。
+`Minecraft.Server` は、このコードベースにおける専用サーバー実行ファイルのエントリーポイントです
 
 主な責務:
-- `server.properties` の読み込みと正規化
-- Windows/Network/Runtime の初期化
-- ワールドのロードまたは新規作成
-- メインループ実行 (ネットワーク進行、XUIアクション、オートセーブ、CLI処理)
-- 安全な保存とシャットダウン
+- 相対パスのファイル I/O を行う前に、カレントディレクトリを実行ファイルのあるフォルダへ切り替える
+- `server.properties` を読み込み、正規化し、不足や不正値を補完する
+- 専用サーバー向けランタイム、接続ログ、アクセス制御を初期化する
+- 対象ワールドをロードまたは新規作成し、実際のセーブ先と `level-id` を整合させる
+- 専用サーバーのメインループを回す (network tick, XUI actions, autosave, CLI input)
+- `banned-players.json` や `banned-ips.json` など運用向けファイルを維持する
+- 新規ワールドの初回保存を実行し、その後安全にシャットダウンする
 
 ## 2. 重要ファイル
 
-### 起動と実行ループ
+### 起動とランタイム
 - `Windows64/ServerMain.cpp`
-  - エントリポイント `main`
-  - 引数パース
-  - 初期化から終了までの実行フロー
-  - メインループとオートセーブ
+  - `PrintUsage()` と `ParseCommandLine()`
+  - `SetExeWorkingDirectory()`
+  - 起動/終了フロー
+  - 新規ワールド初回保存の経路
+  - メインループ、オートセーブ、CLI ポーリング
 
-### ワールド選択とセーブ読み込み
+### ワールド選択とセーブ読込
 - `WorldManager.h`
 - `WorldManager.cpp`
-  - `level-id` 優先でセーブ探索
-  - 見つからない場合は world 名でフォールバック
-  - 非同期完了待機ヘルパー
+  - `level-id` 優先、その後 world 名フォールバックでセーブ探索
+  - storage title と save ID を常にセットで適用
+  - 非同期 storage/server action 完了待ちの helper を提供
 
 ### サーバー設定
 - `ServerProperties.h`
 - `ServerProperties.cpp`
-  - 既定値定義
-  - `server.properties` のパース/正規化/保存
+  - 既定値と正規化レンジ
+  - `server.properties` の読込/補修/書込
   - `ServerPropertiesConfig` の提供
+  - `SaveServerPropertiesConfig()` は `level-name` / `level-id` / `white-list` を書き換える
 
-### ログ出力
+### アクセス制御と BAN / Whitelist 永続化
+- `Access/Access.h`
+- `Access/Access.cpp`
+  - プロセス全体で使うアクセス制御 facade
+  - コンソールコマンドとログイン判定から参照される公開スナップショット管理
+- `Access/BanManager.h`
+- `Access/BanManager.cpp`
+  - `banned-players.json` と `banned-ips.json` の読込/書込
+  - 識別子の正規化と、期限切れエントリを除いた snapshot 出力
+- `Access/WhitelistManager.h`
+- `Access/WhitelistManager.cpp`
+  - `whitelist.json` の読込/書込
+  - ログイン判定と CLI で使う XUID whitelist の正規化管理
+
+### ログと接続監査
 - `ServerLogger.h`
 - `ServerLogger.cpp`
   - ログレベル解釈
-  - タイムスタンプ付き色付きログ
-  - カテゴリ別ログ (`startup`, `world-io`, `console`)
+  - 色付き/タイムスタンプ付きコンソールログ
+  - `startup`, `world-io`, `console`, `access`, `network`, `shutdown` などのカテゴリ
+- `ServerLogManager.h`
+- `ServerLogManager.cpp`
+  - TCP 接続 accept/reject ログ
+  - ログイン/切断の監査ログ
+  - `ban-ip <player>` が使う remote IP キャッシュ
 
-### コンソールコマンド
-- `Console/ServerCli.cpp` (ファサード)
-- `Console/ServerCliInput.cpp` (linenoise 入力スレッド)
+### コンソールコマンドシステム
+- `Console/ServerCli.cpp` (facade)
+- `Console/ServerCliInput.cpp` (linenoise 入力スレッド + completion bridge)
 - `Console/ServerCliParser.cpp` (トークン分解、クォート、補完コンテキスト)
 - `Console/ServerCliEngine.cpp` (実行ディスパッチ、補完、共通ヘルパー)
 - `Console/ServerCliRegistry.cpp` (登録と名前解決)
@@ -53,67 +76,141 @@
 
 ## 3. 起動フロー全体
 
-`Windows64/ServerMain.cpp` の流れ:
-1. `LoadServerPropertiesConfig()` で設定読込
-2. CLI 引数で上書き (`-port`, `-bind`, `-name`, `-seed`, `-loglevel`)
-3. 各サブシステム初期化 (window/device/profile/network/thread storage)
-4. `ServerPropertiesConfig` をゲームホスト設定へ反映
-5. `BootstrapWorldForServer(...)` でワールド決定
-6. `RunNetworkGameThreadProc` でサーバーゲーム開始
-7. メインループ:
+`Windows64/ServerMain.cpp` の主な流れ:
+1. `SetExeWorkingDirectory()` でカレントディレクトリを実行ファイルのフォルダへ切り替える
+2. `LoadServerPropertiesConfig()` で `server.properties` を読み込み、正規化する
+3. `DedicatedServerConfig` へ反映したあと、CLI 引数で上書きする (`-port`, `-ip`/`-bind`, `-name`, `-maxplayers`, `-seed`, `-loglevel`, `-help`/`--help`/`-h`)
+4. プロセス状態、`ServerLogManager`、`Access::Initialize(".")` を初期化する
+5. window/device/profile/network/thread-local 系を初期化する
+6. `ServerPropertiesConfig` をゲームホスト設定へ反映する
+7. `BootstrapWorldForServer(...)` でワールドを決定する
+8. 読み込まれたセーブ ID が正規化後に変わった場合は、`SaveServerPropertiesConfig()` で書き戻す
+9. `RunNetworkGameThreadProc` でホストゲームスレッドを起動する
+10. 新規ワールドが作成された場合は、専用サーバー側で明示的に初回保存を要求する
+11. メインループに入る:
    - `TickCoreSystems()`
    - `HandleXuiActions()`
    - `serverCli.Poll()`
    - オートセーブスケジュール
-8. 終了時:
-   - Action Idle 待機
-   - 最終保存要求
-   - サーバー停止と各サブシステム終了
+12. 終了時:
+   - CLI 入力を停止
+   - save-on-exit を要求してサーバー停止
+   - ネットワーク停止完了を待機
+   - ログ/アクセス制御/ネットワーク/デバイスを終了
 
-## 4. よくある開発作業
+## 4. 現在の運用インターフェース
 
-### 4.1 CLI コマンドを追加する
+### 4.1 起動引数
+- `-port <1-65535>`
+- `-ip <addr>` または `-bind <addr>`
+- `-name <name>` (実行時上限 16 文字)
+- `-maxplayers <1-8>`
+- `-seed <int64>`
+- `-loglevel <debug|info|warn|error>`
+- `-help`, `--help`, `-h`
+
+補足:
+- CLI による上書きは、その起動中のプロセスにだけ効きます
+- 現在サーバーが書き戻す値は `level-name` と `level-id` だけで、ワールド解決時に識別情報が変わった場合に限られます
+
+### 4.2 組み込みコンソールコマンド
+- `help` / `?`
+- `stop`
+- `list`
+- `ban <player> [reason ...]`
+  - 現状では対象プレイヤーがオンラインである必要があります
+- `ban-ip <address|player> [reason ...]`
+  - リテラル IPv4/IPv6 か、オンラインプレイヤーの現在 IP を対象にできます
+- `pardon <player>`
+- `pardon-ip <address>`
+  - リテラルアドレスのみ受け付けます
+- `banlist`
+- `tp <player> <target>` / `teleport`
+- `gamemode <survival|creative|0|1> [player]` / `gm`
+
+CLI 挙動の補足:
+- `cmd` と `/cmd` の両方を受け付けます
+- `ServerCliParser` により引用符付き引数を扱えます
+- 補完は各コマンドの `Complete(...)` で実装します
+
+### 4.3 実行ファイル横に書かれるファイル
+- `server.properties`
+- `banned-players.json`
+- `banned-ips.json`
+
+これは `SetExeWorkingDirectory()` による挙動ですつまり、これらのファイルはシェル上の起動場所ではなく `Minecraft.Server.exe` 基準で解決されます
+
+## 5. よくある開発作業
+
+### 5.1 CLI コマンドを追加する
 
 `/kick` や `/time` のようなコマンド追加時の基本手順:
 
-1. `Console/commands/` にファイル追加
+1. `Console/commands/` にファイルを追加
    - `CliCommandYourCommand.h`
    - `CliCommandYourCommand.cpp`
 2. `IServerCliCommand` を実装
    - `Name()`, `Usage()`, `Description()`, `Execute(...)`
    - 必要なら `Aliases()` と `Complete(...)`
-3. `ServerCliEngine::RegisterDefaultCommands()` に登録
-4. ビルド定義に追加
+3. `ServerCliEngine::RegisterDefaultCommands()` に登録する
+4. ビルド定義に追加する
    - `CMakeLists.txt` (`MINECRAFT_SERVER_SOURCES`)
-   - `Minecraft.Server/Minecraft.Server.vcxproj` (`<ClCompile>`, `<ClInclude>`)
+   - `Minecraft.Server/Minecraft.Server.vcxproj` (`<ClCompile>` / `<ClInclude>`)
 5. 手動確認
    - `help` に表示される
-   - 実行が期待通り
+   - 実行結果が期待通り
    - 補完が `cmd` と `/cmd` の両方で動く
+   - 引用符付き引数が期待通り処理される
 
 参考実装:
 - `CliCommandHelp.cpp` (単純コマンド)
 - `CliCommandTp.cpp` (複数引数 + 補完 + 実行時チェック)
-- `CliCommandGamemode.cpp` (引数解釈 + モード検証)
+- `CliCommandGamemode.cpp` (引数解釈 + エイリアス)
+- `CliCommandBanIp.cpp` (接続メタデータを使うアクセス制御系コマンド)
 
-### 4.2 `server.properties` キーを追加/変更する
+### 5.2 `server.properties` キーを追加/変更する
 
-1. `ServerProperties.h` の `ServerPropertiesConfig` にフィールド追加
-2. `ServerProperties.cpp` の `kServerPropertyDefaults` に既定値追加
-3. `LoadServerPropertiesConfig()` で読み込みと正規化を実装
-   - 既存の read helper を利用 (bool/int/string/int64/log level)
-4. 保存時に維持したい値なら `SaveServerPropertiesConfig()` も更新
-5. 実行時反映箇所を更新
+1. `ServerProperties.h` の `ServerPropertiesConfig` にフィールドを追加/更新する
+2. `ServerProperties.cpp` の `kServerPropertyDefaults` に既定値を追加する
+3. `LoadServerPropertiesConfig()` で読み込みと正規化を実装する
+   - bool/int/string/int64/log level/level type 用の既存 helper を使う
+4. 書き戻し対象にしたいなら `SaveServerPropertiesConfig()` を更新する
+   - ただし現状この関数は、意図的にワールド識別情報だけを永続化します
+5. 実行時反映箇所を更新する:
    - `ApplyServerPropertiesToDedicatedConfig(...)`
-   - `ServerMain.cpp` の `app.SetGameHostOption(...)` など
-6. 手動確認
-   - キー欠損時の自動補完
+   - `ServerMain.cpp` の `app.SetGameHostOption(...)`
+   - CLI 上書きも持たせるなら `PrintUsage()` / `ParseCommandLine()`
+6. 手動確認:
+   - 欠損キーの自動補完
    - 不正値の正規化
-   - 実行時挙動への反映
+   - clamp 範囲が妥当か
+   - 実行時挙動に反映されるか
 
-### 4.3 ワールドロード/新規作成ロジックを変更する
+> 覚えておくと良い正規化ポイント
+- `level-id` は安全な save ID に正規化され、長さ制限も掛かる
+- `server-name` は実行時 16 文字まで
+- `max-players` は `1..8` に clamp される(あとで増やす必要あり)
+- `autosave-interval` は `5..3600` に clamp される
+- `level-type` は `default` または `flat` に正規化される
 
-主な実装は `WorldManager.cpp` にあります。
+### 5.3 BAN / アクセス制御挙動を変更する
+
+主な実装は `Access/Access.cpp`, `Access/BanManager.cpp`, `ServerLogManager.cpp` にあります
+
+変更時の注意:
+- `BanManager` は storage/caching に責務を寄せ、 live-network policy を持ち込みすぎない
+- `Access.cpp` の clone-and-publish スナップショット方式を保ち、読取側がディスク I/O で止まらないようにする
+- `ban-ip <player>` は `ServerLogManager::TryGetConnectionRemoteIp(...)` に依存することを忘れない
+- `SnapshotBannedPlayers()` / `SnapshotBannedIps()` には期限切れエントリを混ぜない
+- 確認項目:
+  - 欠損時に空の BAN ファイルが初回起動で生成される
+  - `ban`, `ban-ip`, `pardon`, `pardon-ip`, `banlist` が動く
+  - オンライン対象の BAN が即時切断まで到達する
+  - 将来 reload 経路を増やしても手動編集が安全に再読込できる
+
+### 5.4 ワールドロード/新規作成ロジックを変更する
+
+主な実装は `WorldManager.cpp` にあります
 
 現在の探索ポリシー:
 1. `level-id` (`UTF8SaveFilename`) 完全一致を優先
@@ -128,19 +225,25 @@
   - 既存ワールドを正しく再利用できるか
   - 意図しない新規セーブ先が増えていないか
   - 終了時保存が成功するか
+  - 新規ワールド時の明示的初回保存が `ServerMain.cpp` から維持されているか
 
-### 4.4 ログを追加する
+### 5.5 ログを追加する
 
 `ServerLogger` の API を利用:
 - `LogDebug`, `LogInfo`, `LogWarn`, `LogError`
-- フォーマット付きは `LogInfof` など
+- フォーマット付きは `LogDebugf`, `LogInfof` など
 
-カテゴリ指針:
-- `startup`: 起動/終了手順
-- `world-io`: ワールドと保存処理
-- `console`: CLI 入出力とコマンド処理
+transport/login/disconnect ライフサイクルに属するイベントなら `ServerLogManager` 側を使います
 
-## 5. ビルドと実行
+推奨カテゴリ:
+- `startup`: 起動ライフサイクル
+- `shutdown`: 停止ライフサイクル
+- `world-io`: ワールド/保存処理
+- `console`: CLI コマンド処理
+- `access`: BAN/アクセス制御状態
+- `network`: 接続/ログイン監査
+
+## 6. ビルドと実行
 
 リポジトリルートで実行:
 
@@ -152,26 +255,32 @@ cd .\build\Debug
 ```
 
 補足:
-- 実行ディレクトリ基準で相対パス解決するため、出力ディレクトリから起動する
-- `server.properties` はカレントディレクトリから読み込まれる
-- Visual Studio の運用はルートの `COMPILE.md` を参照
+- プロセスは起動時にカレントディレクトリを実行ファイルの場所へ切り替えます
+- `server.properties`, `banned-players.json`, `banned-ips.json` はそのため実行ファイル横に読み書きされます
+- Visual Studio ワークフローはルートの `COMPILE.md` を参照してください
 
-## 6. 変更前チェックリスト
+## 7. 変更前チェックリスト
 
-- `server.properties` が空または欠損でも起動できる
+- `server.properties` が欠損または疎でもクラッシュせず起動できる
+- 欠損したアクセス制御ファイルがクリーンブート時に再生成される
 - 既存ワールドが期待した `level-id` でロードされる
-- 新規ワールド作成時の初回保存が実行される
-- CLI 入力と補完が正常に動く
-- 非同期待機ループから `TickCoreSystems()` などを消していない
+- 新規ワールド作成時の明示的初回保存が維持される
+- CLI 入力と補完が引き続き応答する
+- `banlist` 出力が BAN 追加/解除後も破綻しない
+- 非同期待機ループから `TickCoreSystems()` など busy-wait 防止用ティックを消していない
 - 新規追加したソースが CMake と `.vcxproj` の両方に入っている
 
-## 7. トラブルシュート
+## 8. クイックトラブルシュート
 
 - コマンドが認識されない:
-  - `RegisterDefaultCommands()` とビルド定義を確認
+  - `RegisterDefaultCommands()` とビルド定義を確認する
+- `server.properties` や BAN ファイルの読込先が想定と違う:
+  - `SetExeWorkingDirectory()` により実行ファイルのフォルダへ移動していることを確認する
 - オートセーブ/終了時保存がタイムアウトする:
-  - 待機中に `TickCoreSystems()` と `HandleXuiActions()` を回しているか確認
+  - 待機ループ内で `TickCoreSystems()` と `HandleXuiActions()` を回しているか確認する
 - 再起動時に同じワールドを使わない:
-  - `level-id` の正規化と `WorldManager.cpp` の一致判定を確認
+  - `level-id` の正規化と `WorldManager.cpp` の一致判定を確認する
+- `ban-ip <player>` で IP を解決できない:
+  - 対象プレイヤーがオンラインで、`ServerLogManager` に接続 IP がキャッシュされているか確認する
 - 設定変更が効かない:
-  - `ServerPropertiesConfig` へのロードと `ServerMain.cpp` の反映経路を確認
+  - 値が `ServerPropertiesConfig` にロードされ、必要なら `DedicatedServerConfig` にコピーされ、その後 `ServerMain.cpp` で反映されているか確認する