Merge pull request #267 from m1sk9/update/development-and-websitev1.3.0

docs: Move release notes onto the documentation site and correct the docs against the implementation

5 files changed, 56 insertions, 6 deletions

diff --git a/website/src/docs/features/admin.md b/website/src/docs/features/admin.md
index c3a3d2f..3f71dcc 100644
--- a/website/src/docs/features/admin.md
+++ b/website/src/docs/features/admin.md
@@ -24,9 +24,11 @@ Displayed information:
 
 ## Spy Mode
 
-Players with the `lunaticchat.spy` permission (default: op) can view all direct messages sent and received on the server.
+Players with the `lunaticchat.spy` permission (default: op) can view both the direct messages and the channel messages sent on the server.
 
-- Spy players see the original message before romaji conversion
+- Direct messages are delivered to spies, excluding the sender and the recipient
+- Channel messages are delivered to spies, excluding the sender and the channel's own members
+- For direct messages, spies see the original text before romaji conversion. Channel messages reach spies in the same converted form the members see
 - Hover text indicates the message is a spy message
 - Spy players themselves are not included in the normal sender/recipient list
 
@@ -46,6 +48,15 @@ When `checkForUpdates` is `true` (default), the plugin checks for new versions a
 checkForUpdates: true
 ```
 
+## Nightly Builds
+
+Builds produced from the `main` branch outside of a release are marked as nightly, and the plugin says so rather than letting it go unnoticed.
+
+- Every player is warned on join that the build may be unstable, along with a pointer to GitHub Issues
+- `/lc status` shows the same warning, and displays the release channel in yellow instead of green
+
+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.
@@ -68,7 +79,7 @@ language: "ja"   # "en" or "ja"
 
 | Permission | Default | Description |
 |-----------|---------|-------------|
-| `lunaticchat.spy` | op | View all direct messages |
+| `lunaticchat.spy` | op | View all direct and channel messages |
 | `lunaticchat.channelbypass` | op | Bypass channel restrictions |
 | `lunaticchat.noticeupdate` | op | Receive update notifications |
 | `lunaticchat.command.lcv.status` | op | Use the `/lcv status` command |
diff --git a/website/src/docs/features/channel-chat.md b/website/src/docs/features/channel-chat.md
index c06ea39..ff6bab0 100644
--- a/website/src/docs/features/channel-chat.md
+++ b/website/src/docs/features/channel-chat.md
@@ -37,6 +37,19 @@ Players can join multiple channels, but only one channel can be active at a time
 /lc channel status    # Display the current active channel and list of joined channels
 ```
 
+## Sending to Global Chat (`!` Prefix)
+
+While a channel is active, your chat goes to that channel. Prefixing a message with `!` sends that one message to global chat instead, without leaving or switching the channel.
+
+```
+!Hello everyone      # Goes to global chat even while a channel is active
+```
+
+The `!` and any space following it are stripped before the message is sent, so it never appears in the message itself. A message consisting of only `!` is discarded and nothing is sent.
+
+> [!NOTE]
+> The prefix is handled by the chat listener, which is only registered when channel chat, cross-server global chat, or Japanese conversion is enabled. If all three are disabled, a leading `!` stays in the message exactly as typed.
+
 ## Roles and Permissions
 
 Channels have three roles.
@@ -87,6 +100,10 @@ See the `features.channelChat.messageLogging` section on the [Configuration page
 
 Players with the `lunaticchat.channelbypass` permission (default: op) are protected from kicks and bans, and can force-delete channels.
 
+## Spy Mode
+
+Channel messages are not private from administrators. Players with the `lunaticchat.spy` permission (default: op) also receive channel messages, excluding the sender and the channel's own members. See [Spy Mode](/docs/features/admin#spy-mode) for details.
+
 ## Message Format
 
 The display format for channel messages can be customized via `messageFormat.channelMessageFormat` in `config.yml`. See [Message Format](/docs/reference/message-format) for details.
diff --git a/website/src/docs/features/direct-message.md b/website/src/docs/features/direct-message.md
index 07f6cdb..ec0f24e 100644
--- a/website/src/docs/features/direct-message.md
+++ b/website/src/docs/features/direct-message.md
@@ -42,6 +42,17 @@ To message a player on another server, specify the player argument as `playerNam
 /tell <player>@<server> <message>
 ```
 
+`serverName` is the name of the destination server **as registered in your Velocity configuration** (`velocity.toml`), which is what the proxy resolves the target against. Tab completion offers the names and players it currently knows about.
+
+Set `features.velocityIntegration.serverName` on each backend to that same name. It does not affect routing, but it fills `{server}` in cross-server chat and is how a server recognises which players are its own — if it disagrees with the Velocity name, local players are treated as remote in tab completion.
+
+Delivery can fail in two ways, and the sender is told which:
+
+| Reason | Meaning |
+|--------|---------|
+| `SERVER_NOT_FOUND` | No server registered on the proxy has that name |
+| `TARGET_OFFLINE` | The server exists, but that player is not on it — including when they are online on a different server |
+
 ## Notification Settings
 
 Players can individually control the sound notification when receiving direct messages.
diff --git a/website/src/docs/features/japanese-conversion.md b/website/src/docs/features/japanese-conversion.md
index ec1df1b..d98ac87 100644
--- a/website/src/docs/features/japanese-conversion.md
+++ b/website/src/docs/features/japanese-conversion.md
@@ -19,8 +19,11 @@ Conversion is performed in two stages.
 Input:       konnichiha sekai
 Stage 1:     こんにちは せかい
 Stage 2:     こんにちは 世界
+Sent:        konnichiha sekai §e(こんにちは 世界)
 ```
 
+The original text is **not** replaced. What you typed is kept, and the conversion result is appended in parentheses, so both are visible to everyone who receives the message.
+
 ## Conversion Targets
 
 - Normal chat
@@ -48,7 +51,7 @@ Conversion results are cached per word. When the same word is converted again, t
 | `cache.saveIntervalSeconds` | `300` | Interval for saving to disk (seconds) |
 | `cache.filePath` | `"conversion_cache.json"` | Path to the cache file |
 
-When the cache reaches its limit, the oldest 10% of entries are automatically removed.
+When the cache reaches its limit, 10% of the entries are removed. Which entries are dropped is not defined: the in-memory cache is unordered, so eviction is effectively arbitrary rather than oldest-first.
 
 ## API Settings
 
@@ -56,6 +59,11 @@ Settings related to the connection to the Google IME API.
 
 | Setting Key | Default | Description |
 |-------------|---------|-------------|
-| `api.timeout` | `3000` | Request timeout (milliseconds) |
+| `api.timeout` | `3000` | Timeout for a single API request (milliseconds) |
 
 If the API times out or fails, the message is sent in hiragana as-is.
+
+> [!WARNING]
+> Independently of `api.timeout`, converting one message is given an overall budget of **1000 ms**. When that budget runs out the conversion is abandoned and the message is sent exactly as typed, with nothing appended.
+>
+> Because the overall budget is shorter than the default `api.timeout`, raising `api.timeout` above `1000` has no practical effect.
diff --git a/website/src/docs/features/velocity.md b/website/src/docs/features/velocity.md
index 8bc1b70..7842a24 100644
--- a/website/src/docs/features/velocity.md
+++ b/website/src/docs/features/velocity.md
@@ -51,6 +51,8 @@ When `crossServerGlobalChat` is set to `true`, player chat messages are relayed
 
 Each message is assigned a unique ID, and a cache prevents the same message from being displayed more than once. The cache size can be configured with `messageDeduplicationCacheSize` (default: `100`).
 
+Entries expire 60 seconds after they are recorded. If the cache is still over its configured size after expired entries are cleared, the oldest remaining entries are dropped.
+
 ## Cross-Server Direct Messages <Badge type="tip" text="v1.3.0~" />
 
 Setting `crossServerDirectMessage` to `true` lets players exchange direct messages with players on other servers connected to the same proxy.
@@ -80,7 +82,8 @@ The handshake timeout is 5 seconds. If the handshake times out, the state become
 |-------------|---------|-------------|
 | `enabled` | `false` | Enable Velocity integration |
 | `crossServerGlobalChat` | `false` | Enable cross-server global chat |
-| `serverName` | `"Unknown"` | Server name displayed in cross-server chat |
+| `crossServerDirectMessage` | `false` | Enable cross-server direct messages |
+| `serverName` | `"Unknown"` | This server's own name. Fills `{server}` in cross-server chat and is how the server recognises its own players. Set it to the name registered in `velocity.toml` |
 | `messageDeduplicationCacheSize` | `100` | Size of the message deduplication cache |
 
 ## Message Format