minecraft-server/docs/DEFAULT-RANK-COMMANDS-2026-05-07.md

# Default-rank command audit — 2026-05-07

**Test rig:** YOU500 (LuckPerms group `default`, weight 10).
**Reporter:** Operator says `/help` and "homestead/land claiming" don't work for him.

This is a diagnostic document written before any fix. Section 6 ("Applied")
records what was changed live after operator sign-off.

---

## 1. What's actually loaded on the box

Plugins enabled at boot (from `Enabling X` lines in `docker logs`):

```
LuckPerms, Vault, ProtocolLib, FAWE, VoidWorldGenerator, SkinsRestorer,
PlaceholderAPI, Essentials, MiniPlaceholders, AuthMe, AuthLimbo, EZShop,
ProAntiTab, Homestead, CarbonChat, voicechat, CoreProtect, TAB, MiniMOTD,
HelpCommand, EpicGuard (errored), AuctionHouse, Chunky
```

**The `Lands` plugin is NOT loaded.** The directory `/data/plugins/Lands/`
exists with config + data files (probably leftover from a prior install) but
there is **no `Lands*.jar`** in `/data/plugins/`. Land-claiming is handled
exclusively by **Homestead** v5.2.0.0 (free GPL-style alternative; main class
`tfagaming.projects.minecraft.homestead.Homestead`).

This means every reference to `/lands` in our configs is dead text:
- `HelpCommand/config.yml` page 2 advertises `/lands`
- `ProAntiTab/storage.yml` has `lands` in the default whitelist
- `Lands/config.yml` and friends are sitting unused

---

## 2. Default-group LuckPerms snapshot

From `lp export pat-debug` → `/data/plugins/LuckPerms/pat-debug.json.gz`,
the `default` group has only these nodes:

| Node | Value | Notes |
|------|-------|-------|
| `essentials.motd` | **false** | suppress MOTD spam (intentional) |
| `prefix.10.&8[&2Adventurer&8]&r ` | false | prefix off (operator-managed elsewhere) |
| `skinsrestorer.command` | true | base SR command |
| `skinsrestorer.command.gui` | true | open SR GUI |
| `skinsrestorer.command.set` | true | `/skin set <name>` |
| `skinsrestorer.command.set.url` | true | `/skin url <url>` |
| `skinsrestorer.ownskin` | true | apply own MC skin |
| `skinsrestorer.player` | true | be a SR-recognised player |
| various `skinsrestorer.*` | false | restrict admin/edit/clear |
| `weight.10` | true | rank ordering |

The `default` group has **no inheritance** — it's a flat group. Nothing
explicitly grants or denies `bukkit.command.help`, `essentials.help`,
`homestead.commands.region`, `homestead.commands.claim`, etc.

For commands declared `default: true` in their plugin.yml, Bukkit grants
the perm to all players automatically — so the LP node table not listing
them is **expected and fine**.

---

## 3. Why `/help` looks broken

Both EssentialsX and HelpCommand register a `/help` command. Plugin enable
order (from logs): **Essentials** at 13:07:35, **HelpCommand** at 13:07:40.
Bukkit gives the original name to whoever registered first — Essentials
wins `/help`; HelpCommand's command becomes `helpcommand:help`.

EssentialsX's `/help` runs fine for default players (no perm gate on the
command itself), BUT in `Essentials/config.yml`:

```yaml
non-ess-in-help: true
hide-permissionless-help: true
```

`hide-permissionless-help: true` means Essentials hides every plugin's help
entries unless the player has `essentials.help.<plugin>`. The default group
has none of those nodes, so YOU500 sees a near-empty Essentials help page —
indistinguishable from "/help is broken".

Meanwhile our pretty branded help screen (with the racked.ru header,
`&e/lands`, `&e/claim`, etc) is in **HelpCommand's** config and reachable
only via `/helpcommand:help` or the `/hc` admin command. The help-text
that the welcome message and AuthMe login-hint advertise is therefore
unreachable from the bare `/help` token.

**Root cause for `/help`:** plugin-conflict; Essentials shadows HelpCommand
on the bare `/help` token, and Essentials has a hide-by-default policy.

Two viable fixes (pick one):

- **(A) Re-route `/help` to HelpCommand via `commands.yml` alias.** Add:
  ```yaml
  aliases:
    help:
    - helpcommand:help $1-
  ```
  This forces every `/help` invocation to hit HelpCommand's branded screen.
  No LP changes needed. PAT whitelist already allows `help`. Cleanest
  option — matches the rest of our alias style in `commands.yml`.

- **(B) Grant `essentials.help` (and per-plugin children) to default.**
  Keeps Essentials's help. Requires a long perm-list and won't show the
  racked-styled page. Not recommended.

We applied **option A** (see §6).

---

## 4. Why "homestead/land claiming" doesn't work

Homestead claim flow (from its plugin.yml + language file
`/data/plugins/Homestead/languages/en-US.yml`):

1. `/hs create <name>` — create a region. Aliases: `/region`, `/rg`,
   `/homestead`. The Homestead commands `claim` and `unclaim` operate
   against the **target region** stored per-player.
2. `/hs set target <name>` — set which region the next `/claim` will
   add the chunk to. Friendly hover-link is sent right after `/hs create`.
3. `/claim` — adds the chunk you stand in to the target region.
4. `/hs menu` — GUI for trust, flags, etc.

`ProAntiTab/storage.yml` group `default` whitelist contains:
```
help, rules, sethome, home, deletehome, claim, lands, tpaccept, tp, pay,
pm, bal, skin, skin url, skin set, shop, ah, auctionhouse, balance, baltop,
msg, reply, r, back, spawn, delhome, homes, warp, warps, list, login, register
```

It does **NOT** contain `region`, `rg`, `hs`, `homestead`, or `unclaim`.

Because PAT runs with `turn-blacklist-to-whitelist: true`, **every command
not in this list is blocked for default players** — including all four
entry-points to Homestead. So a default player can run `/claim` (and PAT
allows it), but `/claim` returns "set a target region first" because they
were never able to run `/hs create`. The land-claiming workflow is
unreachable.

The dead `/lands` entry in the whitelist does no harm but advertises a
command that doesn't exist on this server.

**Root cause for homestead claiming:** PAT whitelist gap. Operator added
`claim` and `lands` in a previous session but never added the Homestead
master commands. Three of the four entry-points are blocked. There is no
LuckPerms denial — Homestead's plugin.yml declares `homestead.commands.region.*`
and `homestead.actions.regions.*` as `default: true`, so a default player
already has all the perms; only PAT is in the way.

---

## 5. Fix proposed

### 5a. PAT — add Homestead entry-points to default whitelist

Append to `/data/plugins/ProAntiTab/storage.yml` under
`groups.default.commands` (do NOT remove existing entries):

```yaml
      - region
      - rg
      - hs
      - homestead
      - unclaim
```

Reload via RCON: `pat reload`.

Safe because:
- These are the bona-fide Homestead user commands. All four resolve to the
  same Homestead `region` command (one base + three aliases) plus `unclaim`.
- All five commands are declared `default: true` in Homestead's plugin.yml
  — no privilege uplift.
- We are only ADDING, never REMOVING, so existing whitelist semantics are
  preserved.

Optional cleanup (not applied): the dead `lands` entry in the whitelist is
harmless and we leave it for now in case the Lands jar is restored.

### 5b. `/help` routing — alias `/help` → `/helpcommand:help`

Append to `/data/commands.yml` under `aliases:`:

```yaml
  # /help = our branded HelpCommand page (Essentials shadows /help otherwise)
  help:
  - helpcommand:help $1-
```

Apply via RCON: `minecraft:reload` is unsafe; instead let it take effect
on next restart. Since this is a small text-only change and operator is
running active live tests, we apply via a more surgical path: send
`/reload confirm` only if operator wants immediate effect; otherwise
queue for next deploy.

(Decision in §6: we wrote the alias and asked the operator to verify
without forcing a reload.)

Safe because:
- HelpCommand's `/help` has no permission requirement (its plugin.yml
  declares `commands.help` with no `permission:` field).
- PAT whitelist already allows `help` → still allowed after alias.
- Does not change behaviour for ops/admins meaningfully — they get the
  branded page like everyone else.

---

## 6. Applied (live, after operator sign-off)

### 6a. PAT whitelist (applied)

Added five lines under `groups.default.commands` in
`/data/plugins/ProAntiTab/storage.yml`:

```
- region
- rg
- hs
- homestead
- unclaim
```

Reload: `echo 'pat reload' | docker exec -i minecraft-mc rcon-cli`

Verification: `pat reload` returned no errors; YOU500 to confirm
`/hs create test1` succeeds.

### 6b. `/help` alias (applied)

Added to `/data/commands.yml` under `aliases:`:

```yaml
  help:
  - helpcommand:help $1-
```

Effect requires server restart or `/reload confirm` (Bukkit aliases are
loaded once at startup). Operator decides when to bounce.

### 6c. LuckPerms changes

**None needed.** The Homestead and HelpCommand commands are all open by
plugin.yml defaults. The earlier hypothesis of a `false` override on
`bukkit.command.help` or `lands.command.claim` was disproved by the LP
export — the only `false` overrides on `default` are `essentials.motd`
(intentional) and SkinsRestorer admin-action denies (intentional).

Per workspace policy in `feedback_lp_prefixes_locked.md`, prefixes/suffixes
were not touched.

---

## 7. Open items

- The empty `/data/plugins/Lands/` config tree is dead weight. Either
  reinstall the Lands jar (if operator wants the premium plugin) or
  archive the directory and remove the dead `lands` line from PAT
  whitelist. Not blocking.
- HelpCommand page 2 still says `&e/lands` — should be updated to
  `&e/hs create <name>` or similar to match reality. Not blocking, but
  filed in `ROADMAP.md`.
- Consider granting default group some `essentials.help.<plugin>` nodes
  if we ever want fallback `/help` to be useful. Low priority while alias
  is in place.