Admin Guide

Admin Guide

This is the practical handbook for hailsDotGO staff. The admin panel lives at /admin and is available to moderators and above; what you can see and do inside it depends on your role. The sections below follow the panel's tabs (Settings, Users, Raids, Awards, Tags, Tag Requests, Translator Apps, Translations, Pages, Costumes, Donations, Site Stats) and note the minimum role for every action. For what the roles themselves mean, see Accounts and Roles.

Role shorthand used below: Mod+ means moderator, admin, or superadmin; Admin+ means admin or superadmin; Superadmin means only the account named by SUPERADMIN_USER.

Staff protection rules

These are enforced server-side regardless of who clicks the button:

• Other admins cannot target the superadmin: no password reset, rename, disable, role change, special rank change, or pending-role confirm/reject. The superadmin can reset their own password, rename their own account, and set their own special rank from the panel. Note: renaming the superadmin account requires updating the SUPERADMIN_USER environment variable to match, or superadmin status is lost on the next restart. The superadmin's API access and translator flags are always on and cannot be toggled.
• Staff (moderators and admins) cannot be raid-banned or hidden from the directory. Demote them first if it ever comes to that.
• You cannot disable your own account.
• Demoting an admin to any other role automatically revokes their api_access flag.

Settings tab (Admin+)

• Registration toggle: opens or closes public registration. Invite links keep working while registration is closed.

Pages tab (Admin+)

Per-page maintenance toggles for: Raids, DPS, IV Calculator, PvP, Events, Trainers, Shinies, plus two section toggles inside the trainers page (Trainer Directory and Raid Finder), and a Translator Applications toggle. A disabled page renders a maintenance screen with HTTP 503; the Raid Finder toggle also blocks all raid API mutations. When Translator Applications is disabled, logged-in users without an existing application see a "currently closed" message instead of the form.

Invites (Admin+)

Generated from the Settings tab:

• Choose the granted role (user, tester, moderator, admin) and max uses (1 to 50).
• Multi-use invites can only grant user; moderator and admin invites must be single-use.
• Tokens expire after 7 days. Active invites are listed with their use counts and can be cancelled at any time.
• Staff roles granted by invite arrive as a pending role; see user management below.

Users tab (Mod+)

Search and manage every account. Required role per action:

Action	Role	Notes
List users (roles, flags, strikes, tags, trust, raid XP)	Mod+
Reset password	Mod+	Minimum 8 characters
Change username	Mod+	Same validation as registration
Disable / re-enable with reason	Mod+	Disabling revokes all sessions; the reason is shown at login
Hide from / unhide in directory	Mod+	Not usable on staff
Raid ban / unban	Mod+	Not usable on staff; banning immediately removes the user from any queue or lobby
Strikes: list, add (reason required), delete	Mod+	Audit trail of warnings
Change role	Admin+	user, tester, moderator, admin
Confirm or reject a pending staff role	Admin+	For invite-granted moderator/admin roles
Set raid XP	Admin+	0 to 9,999,999; changes the rank ladder position
Set rater weight	Admin+	0.1 to 1.5; the user's trust report reliability
Clear legacy ratings	Admin+	Wipes old star-rating rows for the user
Refresh activity	Admin+	Sets last_raid_at to now (rank decay helper)
Set special rank	Admin+	trusted, content_creator, or clear; unlocks custom lobbies
Toggle API access	Superadmin	Grantable to any account; gates the private API
Toggle translator	Superadmin	Gates the /translate workspace
Assign / remove tags	Mod+	Store-earned custom tags must be managed from Tag Requests instead

Raids tab (Mod+)

Moderation tools for Raid Finder and the Trust and Awards systems.

Lobby moderation

• List live lobbies (Mod+): host, boss, state, member count.
• Force-cancel a lobby (Mod+): uses the same path as a host cancel, so members are returned to the front of the queue with no penalty.

Trust tools

• Event log per user (Mod+): the last 100 trust events with actor, raw delta, weight, applied delta, and note, plus the cached score, effective score, and tier.
• Manual adjust (Admin+): inserts an auditable staff_adjust event (delta between -100 and +100, with a note). It bypasses the per-event clamp so corrections of any size are possible.
• Recompute (Admin+): re-sums the event log into the cached trust_score column if it ever drifts.

Awards management

• List catalog and recent grants (Mod+).
• Create / update / delete awards (Admin+): name, description, icon, color, sort order, active flag.
• Revoke a grant (Mod+).

Grant rank permissions

Each award has a configurable minimum rank required to grant it. The inline dropdown to change the setting is directly in the Awards panel row, no separate edit modal needed. Options are:

• Anyone (default): any logged-in user can grant (if community grants are enabled)
• Trusted+: effective trust tier must be Trusted or above
• Content Creator+: must hold the Content Creator special rank
• Translator+: must have the translator flag
• Tester+: must have the Tester role or above
• Moderator only: Moderators and above only

Admins and Super Admins can always grant any award regardless of the rank setting. The grant award modal shown to users automatically filters to only awards they are eligible to grant.

Tags tab

Colored label pills shown next to usernames.

• List tags and assign or remove them on users: Mod+.
• Create, edit, delete tags in the catalog: Superadmin only.
• Custom tags earned through the store cannot be removed here; handle them through Tag Requests so the request state stays consistent.

Tag Requests tab (Mod+)

Reviews the custom tag requests submitted by Supporter Pack holders (see Store).

• Approve: creates (or recolors) the tag and assigns it. Approval is refused if the user's Supporter Pack has lapsed.
• Reject with a reason: starts the user's 7-day cooldown before they can submit a fresh request. Rejecting an already-approved tag also strips it from the user.
• Request revision with notes: the user can resubmit immediately with a new name or color, without the cooldown.

Translator Apps tab (Admin+)

Reviews applications from users who want to become translators. Applications are gated by the section_translator_apps_enabled toggle in the Pages tab; when disabled, logged-in users without an existing application see a "applications closed" message instead of the form.

• Filter by Pending, Being Reviewed, or All.
• Mark as Reviewing: moves the application from Pending to Being Reviewed, signalling to the applicant that their submission is under active consideration.
• Accept: grants the translator flag immediately so the user can access the workspace.
• Reject: requires a reason (shown to the applicant on their /translate status page).
• Application status (Pending / Being Reviewed / Accepted / Rejected with reason) is visible to the applicant on /translate so they always know where they stand.

Translations tab (Admin+)

Reviews edits submitted from the Translator Workspace:

• List pending edits per locale, approve or reject (with a reason) each one.
• Export a locale's approved overrides as JSON.
• Sync to GitHub: pushes approved community translations to the repository.
• Enable or delete locales: translator-created locales stay hidden from the public language switcher until enabled here.

Donations tab (Admin+)

• Store master toggle: shows or hides the Store page and nav link site-wide. Turning it off does not cancel active perks.
• Store item management: list the catalog (name, slug, price, type, sort order) and toggle items active or inactive. Prices and new items are managed in the database; see Store.

Site Stats tab (visible to all staff)

The tab is visible to moderators and above, but the live stats dashboard requires Admin+ to load (it fetches GET /api/admin/stats): process uptime, goroutine count, heap usage, GC runs, database pool stats (open, in use, idle, waits, wait time), a live DB ping latency, and app counts (total users, active raids, tracked shinies, active sessions).

This tab also contains the Force data refresh button, which is visible to all staff but only executes for the superadmin (calls POST /admin/refresh-data). It triggers an immediate re-fetch of all game data from upstream sources, the same effect as POST /api/refresh (see Data Sources).

Next to it is the superadmin-only Check/Run Scrapers button (POST /admin/check-scrapers). Where Force data refresh only reloads the PoGoAPI game data and localized Pokémon names in the background, Check/Run Scrapers fetches every scraped source synchronously (raids, max battles, events, and all PoGoAPI/PokeAPI data) and renders an inline per-source report: an OK/ERROR badge, item count, payload size, fetch time, and whether each source was already in sync or was updated. Any source whose data changed is applied immediately. Use it to confirm the scrapers are reachable, parse without errors, and that what the site serves matches the current upstream data. An empty result for a source (for example max battles when no Dynamax event is live) is reported as OK, not an error.

Trainer Avatars tab (Admin+)

Lists the full trainer sprite inventory with three filters: name/slug text search, group (Classic / Dreamstone / pokeemerald-expansion), and lock status (All / Locked only / Unlocked only).

Each row shows the sprite thumbnail, character label, and group badge.

• Professor sprites display "Trusted+ (auto-locked)". This lock is enforced server-side and cannot be overridden from this panel.
• All other sprites have a dropdown to set the minimum rank required to pick that avatar:

Option	min_rank	Who can use this avatar
Unlocked, all users	0	Everyone
Trusted+	1	Trusted tier or above
Content Creator+	2	Content Creator special rank or above
Tester+	4	Tester role or above
Moderator+	5	Moderator role or above
Admin only	100	Admin and superadmin only

Hit Save on any row to apply. The change takes effect immediately, the /settings avatar picker filters its list by the requesting user's effective rank, so ineligible users will not see locked sprites.

Costumes tab (Admin+)

The backlog of costumes the game has that nobody has named yet. A costume with no label cannot appear in the shiny picker, so this list is exactly what trainers cannot record yet. Each is shown with its real shiny artwork, which matters: the game's internal code names are misleading (the code "May 2019" is actually a straw hat, not the Detective Pikachu hat), and that is how four costumes historically ended up pointing at the wrong picture. Look at the art before you name it.

• Name a costume: type the label trainers will see and type. It is available in the shiny checklist immediately, with no deploy (the name lands in a server-side overlay merged over the embedded labels.json, the same mechanism as approved translations). Naming is add-only: a code that already has a label cannot be renamed, because labels are user data and renaming one would orphan every saved entry that used it. A confirmation prompt fires if the label shares no word with the art's known name.
• Not a costume: dismiss a code the game flags as a costume but no trainer would ever record, such as the Gimmighoul coins.
• Zoom the art: clicking a costume's thumbnail opens it at full size on every species that can wear it, since most costumes are shared across a whole family and the small preview only shows the first one, which is not much to name from.
• Fetch new costumes: checks the mined-asset data for costume codes the compiled catalog does not know about yet, and reports the asset commit the catalog was built from so you can see how old it is. This is read-only: it cannot pull a new costume in. Picking one up requires regenerating the catalog (make costumes) and deploying, see Building and Development.
• The data-health panel now reports how many costumes are waiting to be named, rather than reporting "in sync" while costumes sat unusable.

Undoing a name is possible only while no saved user_shinies row uses that label; otherwise it is refused, because removing it would blank the costume art on those entries. Names added here also auto-sync back into internal/costumes/labels.json through an auto-opened PR on the costume-labels branch (debounced, on startup and a 12 hour backstop) when GITHUB_TOKEN and GITHUB_REPO are configured, so a name is never stranded only on the server's disk. For how costume data is structured and generated, see Data Sources and Shiny Tracking.

Bug Reports tab (Mod+)

Triage user-submitted bug reports (Bug Reports). The list supports filters (status, label, assignee, text search) and sorting (recent, status, opener, awaiting, priority). For each report you can:

• Reply to the reporter publicly, or post an internal note that only staff see. Internal notes never reopen the report or notify the reporter; a public reply on a resolved/closed report reopens it.
• Set status, priority (low/normal/high/urgent), and assignee (assignment and priority changes are recorded as internal notes).
• Apply labels (7 built-in plus admin-created custom labels; built-ins can be recolored or renamed but not deleted).
• Insert and manage canned responses (saved macros).

Label and macro management (create/edit/delete) is Admin+; everything else on this tab is Mod+.

Player Reports tab (Mod+)

Reports of bad-actor players (Player Reports) land in a shared moderator bucket that every moderator can see. Self-assign to take ownership; "Assigned to me" is your queue. Triage uses the same thread, reply, internal-note, priority, and label tools as the Bug Reports tab.

Enforcement (strikes, raid bans, disabling an account) is done in the Users tab. Once a player has been dealt with, use Resolve (action taken) to close the report and thank the reporter (sends a push and a public thread message). The reported user never sees the report.

Outside the panel

One staff power applies in the field:

• Staff can cancel any lobby and kick any lobby member directly from the raid finder UI.