Merge pull request #297 from m1sk9/feat/release-v1.4.0

feat: Release LunaticChat v1.4.0

5 files changed, 142 insertions, 11 deletions

diff --git a/website/src/docs/configuration.md b/website/src/docs/configuration.md
index fb9f260..4b46b55 100644
--- a/website/src/docs/configuration.md
+++ b/website/src/docs/configuration.md
@@ -22,7 +22,8 @@ The reply says only whether what you edited is in effect. Which settings moved i
 |---|---|---|
 | `messageFormat.*` | Yes | — |
 | `features.*` | — | Yes |
-| `debug`, `checkForUpdates`, `language`, `userSettingsFilePath` | — | Yes |
+| `debug` | Yes | — |
+| `checkForUpdates`, `language`, `userSettingsFilePath` | — | Yes |
 
 The command is available to the console and RCON as well as to players, and requires `lunaticchat.command.lc.reload` (op by default).
 
@@ -46,11 +47,82 @@ A misspelled **key** is still not detected, by either path — an unknown key is
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `debug` | Boolean | `false` | Enable debug logging |
+| `debug` | Boolean or block | `false` | Debug logging. See [Debug Logging](#debug-logging) |
 | `userSettingsFilePath` | String | `"player-settings.yaml"` | Path to the player settings file |
 | `checkForUpdates` | Boolean | `true` | Check for updates on startup |
 | `language` | String | `"en"` | Plugin language (`en` / `ja`) |
 
+## Debug Logging <Badge type="tip" text="v1.4.0~" />
+
+`debug` decides how much LunaticChat writes to the server log, by category. A category is an area of
+the plugin, so instrumenting the chat path does not bury a handshake problem.
+
+| Category | What it reports |
+|---|---|
+| `config` | The configuration read at startup, and what a reload changed |
+| `chat` | How each message was routed, and cross-server deduplication hits |
+| `channel` | Joins, leaves and every refusal, with the reason |
+| `conversion` | Romaji conversion decisions and cache hits |
+| `protocol` | Sub-channel, byte length and message ids on the wire |
+| `velocity` | Handshake, connection state, presence and relay decisions |
+| `storage` | Debounced saves, atomic writes and their size |
+| `command` | Permission denials and command results |
+
+Three spellings are accepted:
+
+```yaml
+debug: false                       # off (yes / no / on / off also work)
+
+debug: true                        # every category
+
+debug: velocity,protocol           # only these
+
+debug:
+  enabled: true
+  categories: [velocity, protocol] # the same, as a block
+```
+
+`enabled: false` wins over any `categories` listed beside it. A category name this build does not
+know is reported as a warning and the categories spelled correctly are still applied.
+
+Debug lines are written at `INFO` with a `[LC/<category>]` prefix, because Paper's stock log4j
+configuration does not print anything below `INFO`.
+
+### Switching Categories at Runtime
+
+```
+/lc debug                     # what is logging now
+/lc debug <category> on|off
+/lc debug all on|off
+```
+
+This changes only the running server — `config.yml` is never rewritten, so a restart or `/lc reload`
+puts the value in the file back in charge. Requires `lunaticchat.command.lc.debug` (op by default).
+
+### Diagnostics Report
+
+`/lc dump` writes `plugins/LunaticChat/debug/report-<timestamp>.txt`, and confirms in chat that it
+wrote one to the plugin folder. The exact path is left to the server log, since the command can be
+granted to someone with no filesystem access. The
+report holds the plugin, protocol, server and Java versions, which features are on, the Velocity
+connection state, and how full each store is. It deliberately contains no message text, player name
+or UUID, so it is safe to paste into a bug report. Requires `lunaticchat.command.lc.dump` (op by
+default).
+
+On the **Velocity proxy** there is no configuration file, so the same switch is read from a system
+property or an environment variable:
+
+```
+java -Dlunaticchat.debug=velocity,protocol -jar velocity.jar
+
+LUNATICCHAT_DEBUG=velocity,protocol
+```
+
+The system property wins over the environment variable. This is deliberately not carried over the
+handshake: the proxy is shared by every backend, so one Paper server must not decide how much the
+proxy logs for everyone else.
+
+
 ## Feature Settings (`features`)
 
 ### Quick Replies (`features.quickReplies`)
diff --git a/website/src/docs/developers/engine.md b/website/src/docs/developers/engine.md
index a65a3f6..1f8956a 100644
--- a/website/src/docs/developers/engine.md
+++ b/website/src/docs/developers/engine.md
@@ -79,6 +79,17 @@ There are two UUID serializers because they serve different purposes. `UUIDSeria
 
 So that Paper and Velocity can handle domain errors as the same types, exceptions are centralized in `engine`. There is no common sealed base — it is a flat structure that directly extends `Exception`. They fall into existence/reference, state, limit, and permission/BAN/KICK categories, and many take `playerId` / `channelId` / `limit` in the constructor and build their own messages. Because there is no base type, callers are expected to catch each individually.
 
+## debug — One switch both platforms read
+
+Debug logging is a contract before it is an implementation: `config.yml` and the proxy's system property must mean the same thing by `velocity,protocol`, and a category added on one side must exist on the other. So the vocabulary lives here and only the writing is left to the platforms.
+
+- `DebugCategory` — the areas that can be logged, each carrying the `key` operators write
+- `DebugCategories.parse` / `resolve` — the one reading of a debug switch, shared by `DebugConfigSerializer` on Paper and `VelocityDebugSwitch` on Velocity. An unknown name is collected rather than thrown, so a typo costs only itself
+- `DebugLogger` — `log(category) { message }`. The lambda is the point: the chat path is instrumented once per message, and while debugging is off the string is never built
+- `DebugState` — the categories currently on, replaceable at runtime by `/lc reload` and `/lc debug`
+
+`JulDebugLogger` (Paper) and `Slf4jDebugLogger` (Velocity) both write at `INFO`, because neither platform's stock logging configuration prints anything below it.
+
 ## permission / command — Neutral abstractions
 
 Permissions and command results are placed in `engine` as neutral representations that can be passed to either the Bukkit or Velocity API.
diff --git a/website/src/docs/features/admin.md b/website/src/docs/features/admin.md
index aa298ba..47964f7 100644
--- a/website/src/docs/features/admin.md
+++ b/website/src/docs/features/admin.md
@@ -42,6 +42,44 @@ The reply says only whether what you edited is in effect. Which settings moved i
 - A `config.yml` the plugin cannot read in full is refused: every unreadable setting is named at once and the running configuration is kept. This is stricter than startup, which falls a single unreadable setting back to its default so the server can come up
 - Every reload is written to the server log, so a format change can be dated later. The file is read off the main thread, and an RCON session closes before the reply reaches it, so RCON callers read the outcome from the log rather than from the command output
 
+## Debug Logging (`/lc debug`) <Badge type="tip" text="v1.4.0~" />
+
+Debug logging is split into categories — `config`, `chat`, `channel`, `conversion`, `protocol`, `velocity`, `storage`, `command` — so that turning it on to chase a handshake does not bury the log under one line per chat message. See [Debug Logging](/docs/configuration#debug-logging) for what each category reports.
+
+```
+/lc debug                     # what is logging now
+/lc debug velocity on
+/lc debug all off
+```
+
+- **Permission**: `lunaticchat.command.lc.debug` (default: op). Usable from the console and RCON
+- The change is **not** written to `config.yml`. A restart or `/lc reload` puts the value in the file back in charge, so a category left on by accident cannot outlive the session
+- Lines are written at `INFO` with a `[LC/<category>]` prefix, because Paper's stock log4j configuration does not print anything below `INFO`
+
+On a Velocity proxy there is no `config.yml`, so the same switch is read from `-Dlunaticchat.debug=velocity,protocol` or the `LUNATICCHAT_DEBUG` environment variable.
+
+## Diagnostics Report (`/lc dump`) <Badge type="tip" text="v1.4.0~" />
+
+Writes everything a maintainer needs to triage a bug report to `plugins/LunaticChat/debug/report-<timestamp>.txt`, and confirms in chat that it wrote one to the plugin folder.
+
+```
+/lc dump
+```
+
+The report holds:
+
+- LunaticChat version and commit, and the protocol version
+- Server software, Bukkit API, Java and OS versions
+- Which features are enabled, and this server's `serverName`
+- Which debug categories are logging
+- Velocity connection state, proxy plugin version and last error
+- Channel and member counts, conversion cache fill, tracked player settings
+- The installed plugins
+
+It deliberately holds **no message text, player name or UUID** — it is meant to be pasted into a public issue.
+
+- **Permission**: `lunaticchat.command.lc.dump` (default: op). Usable from the console and RCON
+
 ## Spy Mode
 
 Players with the `lunaticchat.spy` permission (default: op) can view both the direct messages and the channel messages sent on the server.
@@ -78,15 +116,6 @@ Builds produced from the `main` branch outside of a release are marked as nightl
 
 Nightly builds are not covered by the [security policy](https://github.com/m1sk9/LunaticChat/blob/main/.github/SECURITY.md); use a release build on a production server.
 
-## Debug Mode
-
-Setting `debug` to `true` enables verbose plugin logging. This is useful for troubleshooting issues or submitting bug reports.
-
-```yaml
-# config.yml
-debug: true
-```
-
 ## Language Setting
 
 You can change the language of messages displayed to players. Plugin logs and console output are not affected and remain in English only.
@@ -104,3 +133,5 @@ language: "ja"   # "en" or "ja"
 | `lunaticchat.channelbypass` | op | Bypass channel restrictions |
 | `lunaticchat.noticeupdate` | op | Receive update notifications |
 | `lunaticchat.command.lcv.status` | op | Use the `/lcv status` command |
+| `lunaticchat.command.lc.debug` | op | Use the `/lc debug` command |
+| `lunaticchat.command.lc.dump` | op | Use the `/lc dump` command |
diff --git a/website/src/docs/permissions.md b/website/src/docs/permissions.md
index d55d895..d0493f2 100644
--- a/website/src/docs/permissions.md
+++ b/website/src/docs/permissions.md
@@ -49,3 +49,5 @@ The following permissions are granted to OPs only by default.
 | `lunaticchat.channelbypass` | op | Bypass channel restrictions (kick/ban protection, force deletion) |
 | `lunaticchat.command.lcv.status` | op | Use the `/lcv status` command |
 | `lunaticchat.command.lc.reload` | op | Use the `/lc reload` command |
+| `lunaticchat.command.lc.debug` | op | Use the `/lc debug` command |
+| `lunaticchat.command.lc.dump` | op | Use the `/lc dump` command |
diff --git a/website/src/docs/reference/commands.md b/website/src/docs/reference/commands.md
index 50bcbe9..83904a4 100644
--- a/website/src/docs/reference/commands.md
+++ b/website/src/docs/reference/commands.md
@@ -44,6 +44,21 @@ Re-reads `config.yml` and applies the `messageFormat` settings, then reports whi
 - **Usable from the console and RCON**
 - A `config.yml` that cannot be read in full is refused, and the running configuration is kept
 
+### `/lc debug [category] [on|off]` <Badge type="tip" text="v1.4.0~" />
+
+Shows which debug categories are logging, or switches one. `all` stands for every category. See [Debug Logging](/docs/configuration#debug-logging).
+
+- **Permission**: `lunaticchat.command.lc.debug` (op by default)
+- **Usable from the console and RCON**
+- The change is not written to `config.yml`; a restart or `/lc reload` puts the file back in charge
+
+### `/lc dump` <Badge type="tip" text="v1.4.0~" />
+
+Writes a diagnostics report to `plugins/LunaticChat/debug/` and confirms it in chat; the exact path is left to the server log. It holds versions, enabled features, connection state and store sizes, and no message text, player name or UUID.
+
+- **Permission**: `lunaticchat.command.lc.dump` (op by default)
+- **Usable from the console and RCON**
+
 ### `/lc settings [key] [on|off]`
 
 Views or changes your personal settings. Without arguments, displays the settings list.