feat: add scoped bridge diagnostics and state monitoring

Author: joanroig

docs/getting-started/first-server.md

@@ -4,7 +4,9 @@ Have these ready before you start:
 
 - Whether the server runs **Bedrock or Java**.
 - The address Admincraft should reach, and the port.
-- The bridge's `SECRET_KEY`, or the `rcon.password` if you are connecting straight to a Java server.
+- A bridge access key (`ADMIN_SECRET_KEY`, `COMMAND_SECRET_KEY`,
+  `READ_ONLY_SECRET_KEY`, or legacy `SECRET_KEY`), or the `rcon.password` if you
+  are connecting straight to a Java server.
 - For a self-signed endpoint, the server's `.crt` file.
 
 If any of that is unfamiliar, [what each connection field means](../guides/connection-fields.md) explains where the values come from.
@@ -17,7 +19,7 @@ On a fresh install Admincraft opens on a welcome screen: choose **Add your first
 2. Choose the **Minecraft edition**. It must match the bridge's `SERVER_TYPE`.
 3. Choose the **Connection type**. Do this before the fields below, because the address and port labels change to match it.
 4. Fill in the address and port. What they refer to depends on the connection type: the bridge for every type except direct RCON, where it is the Minecraft server itself.
-5. Enter the **Bridge secret key**, or the RCON password for a direct connection.
+5. Enter the **Bridge access key**, or the RCON password for a direct connection.
 6. For a self-signed endpoint, load the certificate.
 7. Select **Save changes**.
 

docs/getting-started/index.md

@@ -4,7 +4,7 @@ This section is for the person running the Minecraft server or its Admincraft
 bridge. If that infrastructure already exists and you only need to use the
 app, start with [Install Admincraft](install.md) instead.
 
-Admincraft is built around [itzg's Minecraft containers](https://github.com/itzg/docker-minecraft-bedrock-server), which is where it does the most: a live console, world controls and a restart button, on Bedrock and Java alike. It also speaks plain RCON, so an existing Java server can be managed without changing anything about how it runs.
+Admincraft is built around [itzg's Minecraft containers](https://github.com/itzg/docker-minecraft-bedrock-server), which is where it does the most: a live console, world controls and start, stop, and restart buttons, on Bedrock and Java alike. It also speaks plain RCON, so an existing Java server can be managed without changing anything about how it runs.
 
 Two arrangements are therefore possible, and the difference matters enough to choose deliberately.
 
@@ -20,7 +20,7 @@ Two arrangements are therefore possible, and the difference matters enough to ch
 | Live server console | ✅ | ✅ | ❌ RCON cannot stream it |
 | Time, weather, game rules | ✅ | ✅ | ✅ on refresh |
 | Player list | ✅ live | ✅ live | ✅ on refresh |
-| Restart the server | ✅ | ✅ | ❌ no container control |
+| Start, stop, or restart the server | ✅ | ✅ | ❌ no container control |
 | Works in the browser | ✅ | ✅ | ❌ no raw sockets |
 | Can be encrypted without a VPN | ✅ TLS | ✅ TLS | ❌ never |
 | Extra container needed | yes | yes | no |

docs/guides/connection-fields.md

@@ -20,7 +20,7 @@ Admincraft. A direct RCON profile is intentionally different.
 | **Minecraft edition** | Which kind of server the bridge should drive. Bedrock uses the container console; Java uses RCON. | Match your server. |
 | **Address** | The machine running the `websocket` container. The label changes with the connection type, and names the Minecraft server instead for direct RCON. | Tailscale address, `ts.net` hostname, or public IP. |
 | **Bridge port** | The port the bridge listens on. | `8080` normally, `443` behind Tailscale Funnel. |
-| **Bridge secret key** | The bridge's own key, used to sign the token Admincraft sends. | `SECRET_KEY` in the bridge's `docker-compose.yml`. |
+| **Bridge access key** | The bridge key used to sign the token Admincraft sends. Its configured scope determines available controls. | `ADMIN_SECRET_KEY`, `COMMAND_SECRET_KEY`, `READ_ONLY_SECRET_KEY`, or legacy `SECRET_KEY` in the bridge environment. |
 | **Connection type** | Which setup you have. The address and port fields relabel themselves to match. | See [connection security](connection-security.md), or [direct RCON](#direct-rcon-with-no-bridge). |
 
 ## Why Java does not ask for RCON details
@@ -30,7 +30,7 @@ Choosing **Java Edition** changes which backend the *bridge* uses, not where Adm
 ```yaml
   websocket:
     environment:
-      SECRET_KEY: YOUR_SECRET_KEY_HERE   # ← this is the "Bridge secret key"
+      SECRET_KEY: YOUR_SECRET_KEY_HERE   # legacy full-access bridge key
       RCON_HOST: minecraft
       RCON_PORT: "25575"
       RCON_PASSWORD: CHANGE_THIS_RCON_PASSWORD
@@ -91,7 +91,7 @@ The setup from the [Bedrock guide](../server/SERVER_SETUP.md#alternative-tailsca
 | Minecraft edition | `Bedrock Edition` |
 | Address | `my-server.tailnet-name.ts.net` |
 | Bridge port | `443` |
-| Bridge secret key | the `SECRET_KEY` from your compose file |
+| Bridge access key | one of the scoped bridge keys, or legacy `SECRET_KEY` |
 | Connection type | `Public address, trusted certificate` |
 
 The address preview under the dropdown should read `wss://my-server.tailnet-name.ts.net:443`.
@@ -103,7 +103,7 @@ The address preview under the dropdown should read `wss://my-server.tailnet-name
 | Minecraft edition | `Java Edition` |
 | Address | `100.101.102.103` |
 | Bridge port | `8080` |
-| Bridge secret key | the `SECRET_KEY` from your compose file |
+| Bridge access key | one of the scoped bridge keys, or legacy `SECRET_KEY` |
 | Connection type | `Private network (Tailscale, VPN or LAN)` |
 
 The preview reads `ws://100.101.102.103:8080`. That is unencrypted by design, and safe only because Tailscale already encrypts the route. It will not work from the hosted web app: see [using the web app](web-app.md#tailscale-in-the-web-app).
@@ -114,7 +114,8 @@ Work down the chain, since each step rules out everything before it:
 
 1. **Is the preview the address you expect?** It is shown live under the security dropdown.
 2. **Is the port the bridge's port?** Not `19132` (Bedrock game), not `25575` (Java RCON).
-3. **Is the key the bridge's `SECRET_KEY`?** Not the RCON password, not the Minecraft allowlist.
+3. **Is the key one configured by the bridge?** Use an admin, command,
+   read-only, or legacy key—not the RCON password or Minecraft allowlist.
 4. **Does the connection type match the address?** `Private network` gives
    `ws://` and only works over a private route. For **Public certificate**, use
    the exact hostname or IP address covered by the certificate; a hostname is

docs/guides/connection-security.md

@@ -1,6 +1,27 @@
 # Connection security
 
-The Admincraft WebSocket can execute commands and restart the server. Its traffic must therefore be protected either by the network or by TLS.
+The Admincraft WebSocket can execute commands and start, stop, or restart the server container. Its traffic must therefore be protected either by the network or by TLS.
+
+## Choose the least-powerful access key
+
+A current bridge can expose separate keys for different jobs. Put the chosen
+key in the profile's **Bridge access key** field.
+
+| Bridge variable | Logs and diagnostics | Minecraft commands | Container lifecycle |
+| --- | --- | --- | --- |
+| `READ_ONLY_SECRET_KEY` | Yes | No | No |
+| `COMMAND_SECRET_KEY` | Yes | Yes | No |
+| `ADMIN_SECRET_KEY` | Yes | Yes | Yes |
+| `SECRET_KEY` | Yes | Yes | Yes; retained for compatibility |
+
+Use different random values for enabled scopes. For a wall display or status
+dashboard, use a read-only key. For daily server administration that must not
+restart the host container, use a command key. Reserve the admin key for
+trusted devices that need lifecycle controls.
+
+The bridge advertises the capabilities granted to the connected key.
+Admincraft then removes unavailable command suggestions and controls. Older
+bridges that only define `SECRET_KEY` continue to work with full access.
 
 ## Which mode should I choose?
 

docs/guides/interface.md

@@ -28,17 +28,46 @@ Commands you send and recent output are stored per server on this device. Open
 size, timestamps, output limit, automatic scrolling, text filtering, and the
 default filter for common server noise.
 
+With a current Admincraft bridge, reconnecting also replays a bounded recent
+tail from the Minecraft container. Timestamped event IDs prevent the overlap
+from appearing twice. Connection handshakes and automatic status queries do
+not appear as ordinary console lines.
+
+Current bridge connections also complete these diagnostic commands:
+
+- `admincraft help` lists commands available to the current access key.
+- `admincraft status`, `admincraft health`, and `admincraft uptime` inspect the
+  Minecraft container.
+- `admincraft info` summarizes the bridge, protocol, permission, server, and
+  capabilities.
+- `admincraft version` reports the installed bridge version.
+- `admincraft logs [count]` replays up to 1,000 recent lines on demand.
+- `admincraft start-server`, `stop-server`, and `restart-server` manage the
+  container when the profile uses an admin key.
+
+The completion strip and controls follow the capabilities advertised by the
+bridge. A read-only key therefore offers diagnostics and logs without exposing
+Minecraft commands; a command key omits lifecycle actions.
+
 ## Controls
 
 **Controls** turns common commands into buttons for time, weather, difficulty,
-players, game rules, and server restart. **Live commands** contains favorite
+players, game rules, and server start, stop, and restart. **Live commands** contains favorite
 commands saved from the console. The server-response panel at the bottom can be
 collapsed when you need more room.
 
 Some values can be observed from server output; others are refreshed with quiet
 commands or show the last value set from Admincraft. Direct RCON has fewer live
 events because it cannot stream the server log.
 
+Current bridges publish structured container state, world time, and player
+counts. Admincraft uses these for the overview and diagnostics without adding
+`time`, `list`, or connection messages to the visible server transcript.
+
+The Minecraft `stop` command shuts down the game process. The controls under
+**Server** instead ask the bridge to start, stop, or restart the Docker
+container, so it can be started again without shell access.
+
 ## Settings
 
 **Settings** is divided by purpose:
@@ -54,6 +83,19 @@ Device preferences are intentionally not synchronized with server profiles.
 This lets each phone, browser, or desktop keep suitable fonts, layout, and
 console behavior.
 
+## Diagnostics and command audit
+
+Open **Overview → Diagnostics** to inspect the connection state, bridge and
+protocol versions, access-key permission, server state, last heartbeat, last
+log and state event, advertised capabilities, and the most recent connection
+error. **Copy** produces a secret-free summary suitable for an issue report.
+
+The same panel keeps a per-server audit of user-issued commands, their source,
+and whether they were sent or rejected. This is intentionally separate from
+the Minecraft console transcript: background status observations are not audit
+entries, and clearing console output does not turn normal server logs into
+user actions.
+
 ## Notifications
 
 Short notifications appear near the top without blocking controls underneath.

docs/server/SERVER_SETUP.md

@@ -73,7 +73,7 @@ sudo netfilter-persistent save
 
 3. Edit the [docker-compose.yml](docker-compose.yml) file:
 
-   - Change the `services.websocket.environment.SECRET_KEY` variable for a strong password you will use to control the server with Admincraft. Generate one with `openssl rand -hex 32` and keep it out of any public repository: anyone holding it can run commands on your server.
+   - Change the `services.websocket.environment.SECRET_KEY` variable for a strong full-access key you will use to control the server with Admincraft. Generate one with `openssl rand -hex 32` and keep it out of any public repository: anyone holding it can run commands and manage the container. Current bridges can instead use `ADMIN_SECRET_KEY`, `COMMAND_SECRET_KEY`, and `READ_ONLY_SECRET_KEY` to issue least-privilege keys; see [Connection security](../guides/connection-security.md#choose-the-least-powerful-access-key).
    - Change any other variables you like in `services.minecraft`, like the `LEVEL_NAME` or `LEVEL_SEED`, you can see a full list [here](https://github.com/itzg/docker-minecraft-bedrock-server?tab=readme-ov-file#server-properties).
 
 4. Make sure to edit the [backups-config/config.yml](backups-config/config.yml) file, the `worlds` setting should match the one you have introduced in the setting `LEVEL_NAME` in the [docker-compose.yml](docker-compose.yml). You can also change the backups frequency as you like.

docs/troubleshooting.md

@@ -7,7 +7,9 @@ Check that **IP / Hostname** and **Secret Key** are filled in, then save the pro
 ## The connection never reaches Connected
 
 1. Confirm the server address and WebSocket port.
-2. Confirm the `SECRET_KEY` exactly matches the WebSocket configuration.
+2. Confirm the profile's access key exactly matches one of `ADMIN_SECRET_KEY`,
+   `COMMAND_SECRET_KEY`, `READ_ONLY_SECRET_KEY`, or legacy `SECRET_KEY` in the
+   WebSocket configuration.
 3. Check that the WebSocket container is running:
 
     ```bash