docs: roadmap for hard-disable alias cleanup (canonical /pm + others)

docs/ROADMAP-CMD-CLEANUP.md

@@ -0,0 +1,85 @@
+# Roadmap — Command Surface Cleanup
+
+**Goal:** one canonical command per action. Aliases hard-disabled (not just PAT-blocked-with-msg). `/msg` should literally not exist when canonical is `/pm`. Same for all multi-alias commands.
+
+**Why hard-disable vs PAT-block-message:**
+- PAT-block shows a message → still discoverable via tab-complete or "huh that exists?"
+- Hard-disable removes from registration → command tree clean, no message, never discoverable
+- Polish goal: "minimal feels like product, not jank-server"
+
+---
+
+## Canonical decisions (operator-locked)
+
+| Action | Canonical | Aliases to hard-disable | Source override |
+|---|---|---|---|
+| Private msg | `/pm` | `/msg /tell /m /t /w /whisper` | s8n exec 2026-05-07 19:08-19:13 |
+| Reply | `/r` | `/reply` | (decide) |
+| Home set | `/sethome` | `/createhome /sh` | (decide) |
+| Land claim | `/claim` | `/region /rg /hs claim` | (decide) |
+| Help | `/help` | (no aliases) | post-restart aliases.yml routes to helpcommand:help |
+| Nick | `/nick` | `/nickname` | (decide) |
+
+## Mechanisms to hard-disable
+
+**Per-plugin disable** (preferred — clean):
+1. **Essentials** — add to `/data/plugins/Essentials/config.yml` `disabled-commands:` list. Removes from registration. Example:
+   ```yaml
+   disabled-commands:
+     - msg
+     - tell
+     - m
+     - t
+     - w
+     - whisper
+     - reply
+     - createhome
+     - sh
+     - nickname
+   ```
+2. **CarbonChat** — has own /msg /tell /reply etc. Either:
+   - Set `should-register-commands=false` in carbon channel configs (suppress channel cmds)
+   - Use `command-aliases=[]` to clear aliases
+   - For built-in carbon commands: edit `/data/plugins/CarbonChat/command-settings.conf` (per-command toggle if available)
+3. **Bukkit `commands.yml`** — `unknown-command-message: ""` plus alias remap. Server-level fallback. Useful for cmds with no plugin-level disable.
+
+**Server-level alias override** (fallback):
+- `/opt/docker/minecraft/commands.yml`:
+  ```yaml
+  aliases:
+    pm: ["essentials:msg $1-"]      # /pm fires Essentials' /msg
+  ```
+  + Essentials' /msg disabled per above. Result: only /pm works.
+
+**Note**: aliases.yml entries are SERVER-WIDE; perms still apply. Test on staging.
+
+## Implementation phases
+
+### Phase 1 — quick wins (no restart)
+- Edit `/data/plugins/Essentials/config.yml` `disabled-commands:` add `tell, m, t, w, whisper, createhome, sh, nickname` (keep `msg` for now until /pm is canonical)
+- Carbon `should-register-commands=false` for any redundant cmd
+- `essentials reload`
+
+### Phase 2 — canonical /pm switch (during chat-plugin migration)
+- Set `/pm` as the canonical via aliases.yml
+- Disable Essentials `/msg`
+- Update COMMANDS.md
+- Test in-game with YOU500
+
+### Phase 3 — log all command-disable behavior (s8n ask: "log everything")
+- Wrap PAT block messages with audit log (PAT already does this somewhat)
+- Add `EssentialsX` audit-log: `/data/plugins/Essentials/config.yml` debug + log-output
+- Consider Logger Plugin (e.g. spark profiler-style command audit) for full cmd execution log
+
+## Decisions still pending
+- Hard list of all aliases to drop per command
+- Reply: `/r` vs `/reply`
+- Home set: `/sethome` vs `/createhome`
+- Nick: `/nick` vs `/nickname`
+- Should `/co` (CoreProtect) be visible to defaults?
+
+## Risk
+
+- Disabling command at Essentials level may break user muscle memory — onboarding doc will need to make canonical names obvious
+- Carbon's command-settings may not allow per-command disable; may need plugin patch or fork (deferred to chat-plugin migration)
+- Test ALL changes on a clone branch before live restart