v0.1.6a: regional shiny forms, costume overhaul, and smarter IV screenshot scanning

Highlights

Regional shiny forms. Alolan, Galarian, Hisuian, and Paldean variants, plus the alternate battle formes (Therian, Origin, the Deoxys formes, and Sky Shaymin), are now tracked as their own shiny cards with independent counts and sprites. Every entry gained a region selector so older catches can be tagged retroactively, and the Evolve button now offers the correct regional targets (Galarian Meowth to Perrserker, not Persian). See Shiny Tracking.

Costume overhaul. Costumes are now data-driven. The picker offers only the costumes a species actually received (checked against the live game assets), costumed shiny sprites render for every eligible Pokemon (Party Hat Venusaur, the GO Fest Crown Eevee and Pikachu, and a large batch of real Pikachu costumes), and costumed sprites now also appear on public trainer profiles.

Smarter IV screenshot scanning. The scanner reads a Pokemon's exact level straight from the level arc, identifies a nicknamed Pokemon from its candy family, and handles stardust status (Lucky, Shadow, Purified) more accurately. Manual entry now takes stardust exactly as shown on screen and lets the server apply the status discount. See IV Calculator.

Shiny data supplement. A curated supplement fills gaps where the upstream source stopped tracking newer shiny releases (about 21 Pokemon, including the Scorbunny and Sobble lines and the Honedge line), and it survives every data refresh.

Upgrading

This release adds one database migration (section 43): a region column on the shiny collection table. It is additive with a safe default, so there is no data loss. After checking out the tag and rebuilding, run the migrate tool:

go run ./cmd/migrate

The first time on an install with no migration history, baseline at your current version first:

go run ./cmd/migrate -from v0.1.5b
go run ./cmd/migrate

Full instructions for building fresh from this release and for upgrading from a supported version, including the version to migration baseline table, are on the wiki: Releases and Upgrading.

v0.1.5b: trainer cards link straight to profile pages

What's New

Trainer Directory: cards link straight to profiles

• Clicking a trainer card now opens that trainer's full profile page instead of an in-page popup
• Profile pages show everything the popup did and more: identity and badges, trainer code, awards, and the shiny collection
• The View profile link on each card is unchanged; the whole card is now a shortcut to the same place

Smaller improvements

• The popup and its supporting code were removed (about 400 lines of markup, script, and styles), so the directory page ships less to the browser
• Migrate tool: v0.1.5b added to the baseline version map (no new sections; it maps to section 42 like v0.1.5a)

---

Upgrading from v0.1.5a

No database changes. Redeploy the binary and templates as usual; the migrate tool will report nothing pending:

go run ./cmd/migrate -status   # expect: 42 applied, 0 pending

Upgrading from v0.1.4a or earlier

This release includes everything from v0.1.5a (self-service password reset, email confirmation at signup, and the transactional email schema), so older installs have one database section to apply (42: transactional email). With a tracked install:

go run ./cmd/migrate -status   # see applied vs pending
go run ./cmd/migrate           # applies what is pending, through section 42

First time using the migrate tool on an untracked install:

go run ./cmd/migrate -from v0.1.4a   # baseline at YOUR installed version, then apply the rest

The tool knows every release from v0.1.1a through v0.1.5b and lists them if you pass an unknown version. Or apply the pending migrate.sql sections manually, in order. Then redeploy the binary and templates as usual.

Optional environment variables from v0.1.5a: RESEND_API_KEY and MAIL_FROM enable transactional email (see the Configuration wiki page). Leave them unset and password reset and signup confirmation simply skip sending. BASE_URL controls the origin used in emailed links and defaults to the production site. For the full rundown of what you pick up along the way, read the v0.1.5a release notes.

Fresh install

Run schema.sql only. It already reflects every migration through section 42 and seeds the migration history. Do not also run migrate.sql.

Documentation

• Trainer Directory (cards navigate to profile pages)
• Trust and Awards (awards shown on profile pages)
• Shiny Tracking (collections shown on profile pages)
• Configuration (transactional email variables)
• Database Guide

v0.1.5a: self-service password reset and email verification

What's New

Password reset by email

• Lost passwords are now self-service: the login page links to a reset form, and a single-use reset link (valid for one hour) is emailed to the account address
• Responses are identical whether or not the email matches an account, so addresses cannot be probed; requests are rate limited per IP
• Tokens are stored only as SHA-256 hashes, are single-use, and a completed reset retires every other outstanding reset link and signs the account out of all devices
• The admin panel reset remains available and unchanged

Email confirmation at signup (soft verify)

• New accounts receive a confirmation email with a 24 hour link; a banner reminds unconfirmed users with a one-click resend (rate limited, with a per-account cooldown)
• Nothing is gated on confirmation: every feature keeps working while unconfirmed
• Accounts that existed before this release are treated as already confirmed
• Signup now validates the email address format on the server

Transactional email infrastructure

• New internal/mail package sends through the Resend HTTP API from a configurable MAIL_FROM address
• Entirely optional: with RESEND_API_KEY unset, the mailer disables itself and both flows degrade gracefully (no errors, sends are logged and skipped)

Admin tools

• Superadmin "Check/Run Scrapers" button fetches every scraped source synchronously and renders a per-source report, covering the scrapers Force Data Refresh skips
• The admin dashboard's long tab row is now a grouped sidebar (Site Config, Users & Moderation, Community, Localization, Raids, System) with a single dropdown on phones

Smaller improvements

• Shiny search: searching any member of an evolution family returns the whole line
• Built-in bug report labels are fully protected from edits, matching the existing delete protection
• Translation persistence hardening and Platinum trainer avatars
• deploy.ps1 upload retries now report when a retry succeeds instead of recovering silently
• Migrate tool: the v0.1.4a baseline mapping was corrected (it shipped through section 41, the map said 40)

---

Upgrading from v0.1.4a

One new database section (42: transactional email). With a tracked install:

go run ./cmd/migrate -status   # see applied vs pending
go run ./cmd/migrate           # applies section 42

First time using the migrate tool on an untracked install:

go run ./cmd/migrate -from v0.1.4a   # baseline at your version, then apply the rest

Or apply migrate.sql section 42 manually. Then redeploy the binary and templates as usual.

Optional new environment variables: RESEND_API_KEY and MAIL_FROM enable transactional email (see the Configuration wiki page). Leave them unset and password reset and signup confirmation simply skip sending. BASE_URL controls the origin used in emailed links and defaults to the production site.

Fresh install

Run schema.sql only. It already reflects every migration through section 42 and seeds the migration history. Do not also run migrate.sql.

Documentation

• Accounts and Roles (new Email confirmation and Password reset sections)
• Configuration (transactional email variables)
• Database Guide (section 42, email_tokens)
• Deployment
• Getting Started

v0.1.4a -- Report Me Not, player reports, neural OCR, and the full Showdown library

What's New

Bug Reports -- "Report Me Not"

• File a bug from anywhere with the Report Bug button at the bottom of the sidebar.
• Each report is a private, threaded conversation with staff at /reports, split into Active and Closed, with an unread badge in the sidebar.
• Invite up to 4 collaborators onto a report. A reply on a resolved report reopens it.
• Mark your own report resolved or reopen it, and rate how it was handled (editable for 7 days).
• Staff get a full triage workspace: filters and sorting, public replies and internal notes, status, priority, assignee, labels (7 built-in plus custom), and reusable canned responses.

Player Reports

• Report another trainer for bad behavior (spoofing, botting, harassment, hate, threats, scams, impersonation, inappropriate username or profile, spam) from their profile, the social and friends pages, or a raid lobby.
• Pick a reason and add details; the report goes privately to the moderator queue and the reported user is never notified.
• Staff handle player reports in a dedicated admin tab with a shared moderator bucket and self-assignment; resolving a report thanks the reporter.

Neural OCR for IV screenshots (Tesseract removed)

• IV Calculator screenshot scanning now reads CP, name, HP, and stardust through a self-hosted neural OCR microservice (RapidOCR), the same class of recognition the mobile app uses.
• Two-pass CP extraction fixes the white "CP" font and dust costs over bokeh backgrounds; the on-screen clock is no longer mistaken for CP; the pixel arc scan is now a fallback only.
• Tesseract is no longer required on the server.

Full Showdown avatar library

• Added the complete Pokemon Showdown trainer library (~1,314 new sprites) across every generation group, Let's Go, Masters EX, and Pokemon GO.
• The avatar picker gains keyword search by type, role, gender, generation, region, and Pokemon GO faction. Existing avatar selections are unchanged.

Navigation and shiny grid

• Sidebar user row overhaul: your username links to your profile, a compact logout button sits beside it, and a quick-links row adds Social, Friends, My Profile, and Logout.
• Trainer-profile shiny grid is now responsive and sorted by Pokedex number.

Self-hosting: database migration tool

• New cmd/migrate tool upgrades an existing install to the latest schema automatically. It tracks applied sections in a schema_migrations table and runs only what is pending, tolerating sections you already applied by hand.

---

Upgrading from v0.1.3a

Apply the new database migrations (sections 39-41), then deploy.

Recommended, with the new tool:

go run ./cmd/migrate -from v0.1.3a   # baseline at v0.1.3a, then apply 39-41

Or apply migrate.sql sections 39, 40, and 41 manually, in order.

Then:

• Install and run the OCR microservice (ocr-service/; see the README in that directory). It listens on 127.0.0.1:18265; deploy.ps1 syncs it to /opt/hailsdotgo-ocr and restarts it.
• Tesseract is no longer used and can be removed.
• OCR_SERVICE_URL is optional (default http://127.0.0.1:18265/ocr).

See the Database Guide, Deployment, and Configuration wiki pages.

Fresh install

Use schema.sql; it already reflects every migration through section 41 and seeds the migration history. Do not also run migrate.sql. See Getting Started.

Documentation

• Bug Reports
• Player Reports

v0.1.3a -- IV Calculator, trainer avatars, shiny evolution, and mobile API

What's New

IV Calculator (/iv)

• Manual tab: search for any Pokémon by name (form-aware -- Alolan, Galarian, Hisuian variants appear as distinct entries); enter CP, HP, and stardust cost; set trainer level (pre-filled from your profile when logged in); optionally set Pokémon Status (Normal / Shadow / Purified / Lucky) and the calculator normalises the displayed dust cost back to the standard bracket automatically
• Screenshot tab (logged in): upload a PNG/JPEG of the stats screen and the backend extracts CP, HP, dust, name, status, and appraisal stars automatically -- two-pass CP extraction plus arc-scan fallback; three-strategy name detection; Lucky/Shadow/Purified status from keywords and dust inference; gap-based star detection with rainbow hundo recognition; an editable extraction card lets you correct any field before or after calculating
• My Box tab (logged in): save IV results to a personal Pokémon box (up to 3000 entries); view, note, and delete saved spreads
• Supports levels 1.0--51.0 and CP up to 50,000 (Mega Pokémon)
• Requires Tesseract OCR installed on the server for the Screenshot tab; see Getting Started for setup

Trainer Avatars

• 101 new Classic (Showdown) sprites: named characters including villains (Giovanni, Cyrus, Ghetsis, Lysandre, Lusamine, Guzma, Rose, Volo), rivals, N, champions, gym leaders by region, Elite Four members, professors for every generation, and playable characters with outfit variants
• 86 new pokeemerald-expansion (FRLG-style) sprites: Kanto gym leaders, Elite Four, Prof. Oak, Team Rocket grunts, and 60+ trainer class variants; bundled locally under static/sprites/pex/
• Searchable combobox replaces the old dropdown: type to filter with smart ranking (exact → starts-with → contains), sprite thumbnails, cross-set search, and "researcher"/"professor" tag aliases

Admin: Sprite Lock Management

• New Trainer Avatars tab in the admin panel: set per-sprite rank requirements (6 tiers: unlocked / Trusted+ / Content Creator+ / Tester+ / Moderator+ / Admin only)
• Professor sprites are auto-locked to Trusted+ server-side regardless of the table
• The /settings avatar picker filters to only sprites the requesting user's rank can access
• New DB table: sprite_locks (migration 37)

Shiny Collection: Evolution Tracking

• Evolve button on each row in the Caught tab: single-path evolutions confirm inline; branching evolutions (e.g. Gloom → Vileplume or Bellossom) show a sprite picker
• A new Evolved tab lists all shinies that have been evolved through the app
• Evolved entries show a chip label and a subtle visual treatment on your public trainer profile
• evolved_at column records when each evolution was applied (migration 38)
• New Go Pass catch method added (alongside Wild, Egg, Raid, Research, Evolution, Photobomb, Trade, GO Tour)

Mobile Companion API (/api/mobile/v1)

• Session-authenticated versioned API for a companion mobile app; Bearer token auth (same session token as the web cookie)
• Push notifications for raid events (match found, lobby cancelled, 30-second confirm warning); Android via FCM, iOS via APNs -- silently disabled when credentials are absent
• Endpoints mirror web equivalents: auth, profile update, game data, raids, IV Calculator, Pokémon box, Raid Finder
• See API Reference for the full endpoint list

Trainer Level and Shiny Enhancements

• Trainer level field in Settings (1--51); pre-fills the IV Calculator and OCR trainer-level param automatically
• Shiny costume tracking: record costume variants (e.g. Party Hat Pikachu); shown on your collection and public profile
• Event tag: tag shinies to a specific in-game event for filtering

Other Changes

• DPS target comparison: compare a moveset's DPS against all current raid bosses at once
• Awards: per-award configurable minimum rank required to grant (Admin panel → Awards)
• Admin tab bar wraps to a second row on narrow screens instead of clipping off-screen
• Fixed large PNG upload timeouts (ReadHeaderTimeout replaces ReadTimeout)
• Upgraded Pokémon GO level cap to 51 across IV Calculator, counters, and CP multiplier tables

---

Migrating from v0.1.2d

Run the following sections from migrate.sql against your database in order and before deploying:

Section	What it does
30	Creates user_pokemon_box and mobile_device_tokens tables
31	Adds costume and event_tag columns to user_shinies; rebuilds the unique index to include both
32	Adds trainer_level column to users
33	Drops the unique constraint on user_shinies (replaced by a non-unique index)
34	Renames user_friends to user_follows
35	Adds confirm_warned_30s flag to raid_lobby_members
36	Adds min_grant_rank column to awards
37	Creates sprite_locks table
38	Adds evolved_at column to user_shinies

Important: Sections must be applied in order. Section 33 must run before section 34.

If Tesseract is not yet installed on your server, install it now:

# Debian/Ubuntu
apt-get install tesseract-ocr
# Verify
tesseract --version

---

Migrating from v0.1.2c or earlier

Apply all sections from your last applied section through section 38, in order. The section comment headers in migrate.sql include dates to help you identify where to start.

If you are on v0.1.2c: start at section 26.
If you are on v0.1.2b: start at section 24.
If you are on v0.1.2a or earlier: start at section 23.

---

Fresh Install

Follow the Getting Started wiki guide. Use schema.sql -- it already reflects all migrations through section 38. Do not also run migrate.sql on a fresh install.

See Configuration for all environment variables including the new optional push notification credentials.

---

Notes

• Tesseract must be on PATH on the server for the IV Calculator Screenshot tab to return results. The tab loads and accepts uploads without it; OCR extraction will return empty fields if the binary is missing.
• Push notifications require separate FCM (Android) and APNs (iOS) credentials. Both are silently disabled when their environment variables are absent -- no errors, no effect on other features.
• The user_friends → user_follows rename (section 34) is a destructive rename. If your database does not yet have a user_friends table (i.e. you never applied section 27 from v0.1.2d), skip section 34.
• The sprite_locks table starts empty; professor sprites are auto-locked server-side. Use Admin → Trainer Avatars to configure locks for other sprites.
• Trainer level defaults to 40 for users who have not set it; the OCR endpoint also accepts a ?trainer_level= query parameter override.

v0.1.2d -- Social features, notifications, and community feedback

What's New

Friends and Notifications

• Add any trainer as a friend from their profile page (/trainer/{username}); friendship is directional -- you see their raids, not vice versa unless they add you back
• A bell badge in the nav sidebar counts unseen notifications; clicking it opens /notifications, a dedicated page listing all active raids from your friends
• New raid toasts slide in while browsing any page; a short ding plays on each new toast with volume controlled in Settings > Notifications (0--100% visual scale, 50% audio gain cap; default 30%)
• Dismiss individual notifications with x or clear them all at once; visiting the page resets the badge on the next poll cycle

Blocked Users

• Manage your blocked list from Settings > Blocked Users with a live search by username or trainer name
• Block or unblock directly from a trainer's profile page
• Blocking removes any existing friendship in both directions; blocked users cannot re-add you

Community Feedback

• Every public trainer profile now has a Community Feedback section
• Leave positive, neutral, or negative feedback (Pokemon-themed phrases) -- one entry per author/target pair, updatable at any time
• Authors can remove their own entry; moderators can remove any entry; admins manage the option list under Admin > Feedback Options

Trainer Profile Pages

• Each trainer now has a dedicated profile page at /trainer/{username} with a hero layout, layered avatar and favorite Pokemon, badges, tags, and social action buttons
• Your own profile shows a friends preview (5 most recent) with a "View all" link to /friends

Other Changes

• Shiny count badge shown on trainer directory cards when the collection is public
• Translator application form added to the Translate page

---

Migrating from v0.1.2c

Run the following sections from migrate.sql against your database before deploying:

• Section 26 -- adds shinies_hidden column to users
• Section 27 -- creates user_friends and user_blocks tables
• Section 28 -- creates feedback_options table and seeds 10 phrases
• Section 29 -- creates user_feedback table

Section 26 may produce a harmless Duplicate column name 'shinies_hidden' error if you already applied it -- ignore it and continue with sections 27--29.

Sections 27, 28, and 29 use CREATE TABLE IF NOT EXISTS and INSERT IGNORE, so they are safe to re-run.

---

Migrating from v0.1.2a or v0.1.2b

Apply all sections from your last applied section through section 29, in order. Check the section comment headers in migrate.sql to identify which sections are new for you.

---

Fresh Install

Follow the Getting Started wiki guide. Use schema.sql to create the database -- it already reflects the full current schema including all migrations. Do not also run migrate.sql sections on a fresh install.

See the Database Guide for schema details and the Configuration page for all environment variables.

---

Notes

• Friendships are directional: adding someone as a friend does not automatically add you back
• Blocking removes friendship in both directions
• The 10 feedback seed phrases (section 28) are inserted with INSERT IGNORE -- re-running is safe
• All new social features are documented in the Social Features wiki page

v0.1.2c

v0.1.2c -- 2026-06-18

Post-release patches (no functional change; deploy behaviour is identical):

• Unnecessary code comments removed across 10 source files (Go handlers and TypeScript); deploy.ps1 local helper renamed from FileHash to Get-LocalFileHash to resolve a PSScriptAnalyzer warning.
• Credits page API tab corrected: "four endpoints" fixed to reflect the actual seven rate-limited endpoints; events 30-minute refresh cadence added to the cache note; new Community Data section documenting /api/awards, /api/awards/of/{username}, and /api/shinies/of/{username}; POST /api/refresh added to the Private API table.

---

This release gives the Raid Finder its own page, adds shiny collection display
to trainer cards with a matching privacy toggle, and fixes a parser regression
in the game data layer. The only database change is a single ALTER TABLE to
add the shinies_hidden column; everything else is a drop-in deploy.

---

What's in this release

Raid Finder -- dedicated page at /raidfinder

• The Raid Finder has moved from the Trainers page tab to its own route at
  /raidfinder; a nav link appears automatically when RaidFinderEnabled is
  on in the admin Pages tab
• Logged-out visitors see the full page content blurred behind a frosted-glass
  overlay with Login and Sign Up prompts -- the UI is visible but not interactive
• Logged-in users who have not yet set a Trainer Name and Trainer Code see a red
  warning banner explaining they cannot join raids until the profile is updated,
  with a direct link to Settings
• The Trainer Directory page (/trainers) is now a single-section layout; the
  Raid Finder tab has been removed from it entirely
• See Raid Finder
  on the wiki for full usage documentation

Shiny collection on trainer cards

• Trainer cards in the directory now show a collapsible My Collection section
  at the bottom of the profile modal; clicking it expands inline to show the
  trainer's full shiny collection with sprites, form badges, and capture methods
• The section only appears when the trainer's profile is public and they have not
  opted out; see Privacy below
• A new Hide shiny collection toggle in Settings > Privacy lets any user
  opt out without affecting the rest of their public profile
• New public endpoint GET /api/shinies/of/{username} backs this feature;
  it returns an empty array when the profile is private or the toggle is on
• Requires migration step 26 (one ALTER TABLE; see Migrating below)
• See Shiny Tracking
  and Trainer Directory

Translator workspace

• No new changes to the translator workflow in this release; it shipped in
  v0.1.2b and is fully operational
• Fresh installs: the application flow, workspace, admin review queue, and
  GitHub sync are all available out of the box after running schema.sql
• See Translator Workspace
  for the full setup and usage guide, including the two environment variables
  required for GitHub sync (GITHUB_TOKEN, GITHUB_REPO)

Internal fix -- max battles endpoint

• The game data layer (internal/pogodata/pogodata.go) was returning an error
  when no Max Battles were active because the upstream API returns a flat JSON
  array in that case instead of the expected tier-keyed object; both shapes are
  now handled correctly

---

Fresh install from this release

These steps are self-contained. The wiki covers each topic in greater
depth -- see the Documentation section at the bottom.

Prerequisites

Requirement	Minimum version
Go	1.25
Node.js + npm	18
MySQL	8.0
OpenSSH client	any (deploy only)

No C toolchain needed (CGO_ENABLED=0).

1. Clone at this tag

git clone --branch v0.1.2c https://github.com/Hailey-Ross/hailsDotGO.git
cd hailsDotGO
npm install

2. Configure environment

cp .env.example .env

Edit .env and set at minimum:

Variable	Required	Notes
DB_HOST	Yes	e.g. localhost:3306
DB_USER	Yes	MySQL username
DB_PASS	Yes	MySQL password
DB_NAME	Yes	e.g. hailsdotgo
SUPERADMIN_USER	Yes	Exact username you will register first
CSRF_KEY	Strongly recommended	64 hex chars: openssl rand -hex 32
PORT	No	Default 8080
PAYPAL_*	Store only	Omit entirely if not using the store
GITHUB_TOKEN / GITHUB_REPO	Translation sync only	Omit if not using GitHub locale sync

3. Create the database

Use schema.sql for all fresh installs. Do not run migrate.sql on a fresh
install -- it is for upgrading existing deployments only.

mysql -u your_db_user -p < schema.sql

schema.sql creates the database (hailsdotgo), all tables (including
shinies_hidden from this release), and seeds site_settings, store_items,
awards, and locales. Registration is seeded closed; all feature pages are
seeded enabled.

4. Build

# TypeScript bundles -> static/js/
npm run build

# Go binary (current platform)
go build -o hailsDotGO .

Cross-compile for Linux from Windows or macOS:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o hailsDotGO-linux .

5. Run

Export your .env values, then:

# bash
set -a; source .env; set +a
./hailsDotGO

Visit http://localhost:8080. On first start the server fetches game data from
upstream sources; if they are unreachable it falls back to embedded snapshot data.

6. Bootstrap the superadmin account

SUPERADMIN_USER must be set to the exact username you plan to register.

-- Temporarily open registration
UPDATE site_settings SET setting_value = '1' WHERE setting_key = 'registration_open';

Register at /register using that username, then close registration again from
the admin panel at /admin (or set the value back to '0' in SQL).

7. Deploy to a server (optional)

Run deploy/setup.sh once on the server as root, then run deploy.ps1 from
Windows (reads .env, cross-compiles, uploads via SSH with SHA256 manifest
diffing). See the Deployment wiki page for the full walkthrough.

---

Migrating to v0.1.2c from v0.1.2b

Important: Run the database migration BEFORE deploying the new binary.
The new binary expects the schema to be up to date; running an old binary
against a new schema is also unsupported.

From v0.1.2b

One new section since v0.1.2b:

Section	What it adds
26	shinies_hidden column on users -- privacy flag for the shiny collection

Copy and run section 26 from migrate.sql against your live database:

-- 26. Shiny collection privacy flag (2026-06-18)
ALTER TABLE users ADD COLUMN shinies_hidden TINYINT(1) NOT NULL DEFAULT 0 AFTER directory_hidden;

Existing users default to 0 (collection visible), which matches the previous
behaviour. Users can opt out at any time via Settings > Privacy.

From v0.1.1a or earlier

Apply all 26 sections in migrate.sql in order. Sections are numbered and
sequential; do not skip any.

After the migration: update and rebuild

git fetch --tags
git checkout v0.1.2c
npm install
npm run build
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o hailsDotGO-linux .
# then deploy as normal

---

Security notes

• Set CSRF_KEY -- all state-changing endpoints enforce the CSRF token;
  the key should be 64 random hex characters. If unset the server falls back to
  a zero key, which is insecure in production. Generate one with
  openssl rand -hex 32.
• Privacy flags are enforced server-side -- shinies_hidden, profile_public,
  and directory_hidden are all checked in the handler before any data is
  returned; the API always returns an empty result rather than an error, so
  callers cannot distinguish "hidden" from "does not exist".
• The translator workspace requires a scoped token -- if you enable GitHub
  sync, use a fine-grained personal access token with Contents and Pull requests
  read/write scopes on the one repository only; do not use a classic token with
  broad repository access.
• See Configuration
  and Accounts and Roles
  for the full variable reference and role/permission model.

---

Documentation

As of 2026-06-18, the wiki is fully current with this release.
Every topic below has been reviewed against the v0.1.2c codebase. If you are
reading this in the future, the wiki may have evolved; the steps above are
self-contained and do not depend on the wiki being current.

Topic	Wiki page
Full setup walkthrough	Getting Started
All environment variables	Configuration
Schema, migrations, and backups	Database Guide
Server provisioning and deploy scripts	Deployment
TypeScript build pipeline	Building and Development
Roles, staff, and superadmin	Accounts and Roles
Admin panel guide	Admin Guide
Raid Finder	Raid Finder
Trust system and awards	Trust and Awards
Shiny De...

v0.1.2b

v0.1.2b -- 2026-06-11

Post-release patch: deploy.ps1 uses Get-FileHash instead of the
implicit alias FileHash (PSScriptAnalyzer PSAvoidUsingCmdletAliases).
No functional change; deploy behaviour is identical.

---

This release marks the end of the incremental migration era. schema.sql is
now the canonical starting point for all fresh installs; after this release,
migrate.sql will be reset and future schema changes will be tracked fresh.
All previous releases are deprecated and unsupported.

---

What's in this release

Raid Finder v2 -- matchmaking and lobbies

• Per-boss matchmaking queues replace the old browse-and-join board
• Queue priority, confirm windows, invite windows, and a post-raid
  feedback flow (commend/dislike), all enforced server-side with timers
• Raid Finder host reliability tracking: hosts whose lobbies repeatedly
  end without a raid starting receive minor trust penalties after a
  free-pass window

Trust and awards system

• Behavioral trust scores replace star ratings: commends, dislikes,
  confirm timeouts, invite failures, early leaves, and raid successes
  are weighted events; staff reports carry fixed heavy weight
• Five community awards seeded; staff can grant them, with optional
  community granting behind a trust-score gate
• Special ranks (Trusted, Content Creator) grantable by admins

DPS calculator improvements

• Sprite search pickers for attacker and target selection
• Mobile-friendly compare cards at narrow widths
• Type-effective DPS vs a selected target Pokemon
• Target selection persisted for logged-in users (localStorage)

Translator workspace

• Full translator application flow with admin review (accept/reject)
• Community locale submission and admin-controlled GitHub PR sync
• Runtime locale overlay survives redeploys

API and admin improvements

• Private API access grantable to any user account (not just admins)
• Superadmin cannot be targeted by any admin action
• Admin user detail modal and awards/trust drilldown modals

Localization

• All user-facing strings now use locale keys (en/es/fr/de/ja)
• Pokemon names localized via PokeAPI species names

---

Fresh install from this release

These steps are self-contained. The wiki covers each topic in greater
depth -- see the Documentation section at the bottom.

Prerequisites

Requirement	Minimum version
Go	1.25
Node.js + npm	18
MySQL	8.0
OpenSSH client	any (deploy only)

No C toolchain needed (CGO_ENABLED=0).

1. Clone at this tag

git clone --branch v0.1.2b https://github.com/Hailey-Ross/hailsDotGO.git
cd hailsDotGO
npm install

2. Configure environment

cp .env.example .env

Edit .env and set at minimum:

Variable	Required	Notes
DB_HOST	Yes	e.g. localhost:3306
DB_USER	Yes	MySQL username
DB_PASS	Yes	MySQL password
DB_NAME	Yes	e.g. hailsdotgo
SUPERADMIN_USER	Yes	Exact username you will register first
CSRF_KEY	Strongly recommended	64 hex chars: openssl rand -hex 32
PORT	No	Default 8080
PAYPAL_*	Store only	Omit entirely if not using the store
GITHUB_TOKEN / GITHUB_REPO	Translation sync only	Omit if not using GitHub locale sync

3. Create the database

For this release and all fresh installs going forward, schema.sql is
the complete starting point. Do not run migrate.sql on a fresh install.

mysql -u your_db_user -p < schema.sql

schema.sql creates the database (hailsdotgo), all 26 tables, and seeds
site_settings, store_items, awards, and locales. Registration is
seeded closed; all feature pages are seeded enabled.

4. Build

# TypeScript bundles -> static/js/
npm run build

# Go binary (current platform)
go build -o hailsDotGO .

Cross-compile for Linux from Windows or macOS:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o hailsDotGO-linux .

5. Run

Export your .env values, then:

# bash
set -a; source .env; set +a
./hailsDotGO

Visit http://localhost:8080. On first start the server fetches game data from
upstream sources; if they are unreachable it falls back to embedded snapshot data.

6. Bootstrap the superadmin account

SUPERADMIN_USER must be set to the exact username you plan to register.

-- Temporarily open registration
UPDATE site_settings SET setting_value = '1' WHERE setting_key = 'registration_open';

Register at /register using that username, then close registration again from
the admin panel at /admin (or set the value back to '0' in SQL).

7. Deploy to a server (optional)

Run deploy/setup.sh once on the server as root, then run deploy.ps1 from
Windows (reads .env, cross-compiles, uploads via SSH with SHA256 manifest
diffing). See the Deployment wiki page for the full walkthrough.

---

Migrating to v0.1.2b from a previous release

Important: Run the database migrations BEFORE deploying the new binary.
The new binary expects the schema to be up to date; running an old binary
against a new schema is also unsupported.

Identify your starting point

Find the last section you ran in migrate.sql. The sections are numbered 1-25;
each has a comment header with a description and date.

From v0.1.2a

Sections 22-25 are new since v0.1.2a. Apply each one in order against your
live database:

Section	What it adds
22	Raid Finder v2 tables: raid_lobbies, raid_lobby_members, raid_queue, trust_events, awards, award_grants; adds trust_score, special_rank, rater_weight, raid_xp, last_raid_at to users; seeds site_settings trust/awards gates and the 5 community awards
23	locales table; seeds es, fr, de as enabled; translation_edits table and users.translator flag
24	Extends trust_events.event_type enum to include host_unfulfilled
25	translator_applications table

-- Copy and run sections 22 through 25 from migrate.sql, in order.
-- Each section is delimited by a numbered comment block.

From v0.1.1a or earlier

Apply all 25 sections in migrate.sql in order. Sections are numbered and
sequential; do not skip any.

After the migrations: update and rebuild

git fetch --tags
git checkout v0.1.2b
npm install
npm run build
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o hailsDotGO-linux .
# then deploy as normal

Note: migrate.sql is reset after this release

migrate.sql will be archived after v0.1.2b. Future schema changes will use a
fresh sequential format starting from section 1. If you are running a
post-v0.1.2b development build, refer to the current migrate.sql in the
repository for the applicable sections.

---

Documentation

As of 2026-06-11, the project wiki is fully current with this release.
Every topic below has been reviewed against the v0.1.2b codebase. If you are
reading this release note in the future, the wiki may have evolved; the steps
above are self-contained and do not depend on the wiki being current.

Topic	Wiki page
Full setup walkthrough	Getting Started
All environment variables	Configuration
Schema, migrations, and backups	Database Guide
Server provisioning and deploy scripts	Deployment
TypeScript build pipeline	Building and Development
Roles, staff, and superadmin	Accounts and Roles
Admin panel guide	Admin Guide
Raid Finder v2	Raid Finder
Trust system	Trust and Awards
Translator workflow	Translator Workspace
Day-2 operations	Operations
Public JSON API	API Reference

v0.1.2a (Deprecated)

Deprecated. This release is superseded by v0.1.2b and is no longer supported. Please upgrade.

---

Beta Warning -- hailsDotGO is in active development. This release is not recommended for production use. APIs, database schema, and configuration may change without notice between versions.

---

What's new in v0.1.2a

• Events page with full details -- current and upcoming Pokemon GO events now display complete details on site (bonuses, featured Pokemon, shinies, raid bosses, research tasks, GO Pass ranks). The server scrapes the matching LeekDuck event page, sanitizes it server side, and caches it to disk, so visitors never need to leave the site
• Shiny Dex -- the shiny gallery is now its own page: every available shiny Pokemon, how to find it, and a normal vs shiny sprite comparison
• Raids moved to pokemon-go-api, plus Max Battles -- live raid bosses (via LeekDuck) and the new Max Battles section (via snacknap) are fetched from pokemon-go-api, cached to disk, and refreshed every 4 hours; the raids page gained tier tabs
• DPS Calculator redesign -- Pokemon are chosen with a sprite search picker (suggestions show sprites, selections show a larger sprite with type badges); the Compare tab target is a single search box listing current raid bosses first with tier tags, with a Custom types toggle; compare results on phones render as ranked attacker cards instead of a sideways-scrolling table
• Public API hardening -- per-IP rate limit of 10 requests per 2 minutes on public endpoints, plus an aggregate bandwidth cap of 15 MB per 5 minutes per IP; the site frontend itself is exempt via the session endpoint /api/app/data
• Admin panel upgrades -- Users tab redesigned as a mini-card grid with a click-to-open modal detail view; account suspension with an optional staff-entered reason shown to the user on login; Custom Tag Requests moved to their own tab with admin revoke
• Custom tag limits -- weekly submission cooldown and a color change rate limit for supporter custom tags
• Automatic asset cache busting -- static asset URLs carry a content hash, so every deploy invalidates browser caches without manual version bumps
• Disk cache -- fetched raid data and scraped event pages persist in a cache directory (configurable via the new optional CACHE_DIR env var, default cache), so the app serves stale data instead of nothing when an upstream fetch fails

---

Prerequisites

Requirement	Version
Go	1.25+
Node.js + npm	18+
MySQL	8+
Caddy (or other reverse proxy)	2+

---

Fresh Install

1. Clone the repo

git clone https://github.com/Hailey-Ross/hailsDotGO.git
cd hailsDotGO
git checkout v0.1.2a

2. Create your .gitignore

This repository no longer ships a .gitignore. If you fork the project or track your own changes, copy the provided template before doing anything else so build output, secrets, and runtime caches never get committed:

cp .gitignore.example .gitignore

This covers the compiled binaries, static/js/ (esbuild output), node_modules/, .env and app.env, the deploy manifest, and the runtime cache/ directory.

3. Install frontend dependencies

npm install

4. Configure environment

cp .env.example .env

Edit .env with your values:

Variable	Required	Description
DB_HOST	Yes	MySQL host and port -- e.g. localhost:3306
DB_USER	Yes	MySQL username
DB_PASS	Yes	MySQL password
DB_NAME	Yes	MySQL database name (e.g. hailsdotgo)
SUPERADMIN_USER	Yes	Username that always has full admin privileges
CSRF_KEY	Recommended	64-char hex string -- generate with openssl rand -hex 32
PORT	No	HTTP listen port, default 8080
CACHE_DIR	No	Directory for fetched game data and scraped event pages, default cache
PAYPAL_CLIENT_ID	Store only	PayPal REST API client ID
PAYPAL_CLIENT_SECRET	Store only	PayPal REST API client secret
PAYPAL_MODE	Store only	sandbox or live
PAYPAL_WEBHOOK_ID	Store only	PayPal webhook ID for payment confirmation

CSRF_KEY is optional but strongly recommended. Without it, CSRF tokens regenerate on every restart and invalidate all active login sessions.

5. Set up the database

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS hailsdotgo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p hailsdotgo < schema.sql

schema.sql creates all tables and seeds the required site_settings rows (all pages default to enabled, registration defaults to closed). The base tables already include every column added by past migrations, so a fresh install needs nothing beyond the file itself.

6. First admin account

Registration is closed on a fresh install. To create your first account:

Option A -- open registration temporarily:

UPDATE site_settings SET setting_value = '1' WHERE setting_key = 'registration_open';

Set SUPERADMIN_USER=yourusername in .env, start the server, register at /register, then close registration from the admin panel.

Option B -- promote via SQL after registering:

UPDATE users SET role = 'admin' WHERE username = 'yourusername';

7. Build

# TypeScript (outputs to static/js/)
npm run build

# Go binary (new module dependencies download automatically)
go build -o hailsDotGO .

Or: make build (runs both).

Cross-compile for Linux from Windows:

$env:GOOS = "linux"; $env:GOARCH = "amd64"; $env:CGO_ENABLED = "0"
go build -ldflags="-s -w" -o hailsDotGO-linux .

8. Run locally

# Terminal 1 -- recompile TypeScript on save
npm run watch

# Terminal 2 -- Go server
go run .

Visit http://localhost:8080

---

Server Deployment (Linux / systemd)

Create service user and directory

sudo useradd --system --no-create-home --shell /usr/sbin/nologin hailsdotgo
sudo mkdir -p /opt/hailsdotgo
sudo chown hailsdotgo:hailsdotgo /opt/hailsdotgo

The service user must own /opt/hailsdotgo so the app can create its cache/ directory there at runtime.

Copy files to the server

/opt/hailsdotgo/hailsDotGO     <- compiled Linux/amd64 binary
/opt/hailsdotgo/app.env        <- your .env (chmod 600, owned by hailsdotgo)
/opt/hailsdotgo/templates/     <- all .html files from templates/
/opt/hailsdotgo/static/        <- static/ directory (css, js, sprites)

Install and start the service

A ready-made unit file is included at deploy/hailsdotgo.service. The binary reads configuration from process environment variables only, so make sure the unit's [Service] section points at your env file (add this line if it is not present):

EnvironmentFile=/opt/hailsdotgo/app.env

Then install and start:

sudo cp deploy/hailsdotgo.service /etc/systemd/system/hailsdotgo.service
sudo systemctl daemon-reload
sudo systemctl enable hailsdotgo
sudo systemctl start hailsdotgo

The service runs as the hailsdotgo user and restarts automatically on failure. The server needs outbound HTTPS access to pogoapi.net, the pokemon-go-api and ScrapedDuck GitHub feeds, leekduck.com, and pokeapi.co. No API keys are required for any data source.

---

Reverse Proxy (Caddy)

A sample Caddyfile is included at deploy/Caddyfile. The relevant block:

yourdomain.com {
    encode gzip zstd
    reverse_proxy localhost:8080
}

Replace yourdomain.com with your actual domain. Caddy provisions HTTPS automatically via Let's Encrypt.

sudo systemctl reload caddy

---

Upgrading from v0.1.1a

1. Check out the release

git fetch --tags
git checkout v0.1.2a

2. Create your .gitignore

The tracked .gitignore was removed from the repository in this release and replaced with .gitignore.example, so checking out v0.1.2a deletes the old one from your working tree. Recreate it immediately:

cp .gitignore.example .gitignore

Without this step, git status will start showing binaries, static/js/ output, node_modules/, your .env, and the runtime cache/ directory as untracked files, and they are one careless git add away from being committed.

3. Apply database migrations

Two migration blocks were added to the bottom of schema.sql since v0.1.1a. Run them once against your existing database:

-- Custom tag weekly cooldown + color rate limiting
ALTER TABLE users
  ADD COLUMN tag_requested_at DATETIME NULL AFTER last_seen_at;

CREATE TABLE IF NOT EXISTS tag_color_changes (
  id         INT UNSIGNED NOT NULL AUTO_INCREMENT,
  user_id    INT UNSIGNED NOT NULL,
  changed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tcc_user_time (user_id, changed_at),
  CONSTRAINT fk_tcc_user FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Account suspension reason
ALTER TABLE users
  ADD COLUMN disabled_reason VARCHAR(255) NOT NULL DEFAULT '' AFTER disabled;

No other schema changes are required. No site_settings rows need to be added.

4. Environment

No new variables are required. One optional variable was added:

Variable	Required	Description
CACHE_DIR	No	Directory for fetched raid data and scraped event pages, default cache (created at runtime in the working directory)

On a systemd deployment the default resolves to /opt/hailsdotgo/cache. Confirm the service user owns /opt/hailsdotgo (it does if you followed the v0.1.1a setup) so the directory can be created.

5. Rebuild

npm install        # no new packages, but safe to re-run
npm run build      # now also bundles the new static/js/shinydex.js
go build -o hailsDotGO .   # new Go modules (goquery, bluemonday) download automatically

6. Re...

v0.1.1a (Deprecated)

Deprecated. This release is superseded by v0.1.2b and is no longer supported. Please upgrade.

---

Beta Warning -- hailsDotGO is in active development. This release is not recommended for production use. APIs, database schema, and configuration may change without notice between versions.

---

What's new in v0.1.1a

• Page maintenance toggles -- admins can enable/disable individual pages (Raids, DPS, PvP, Events, Trainers, Trainer Directory, Raid Finder, Shinies) from the admin panel; disabled pages show a maintenance screen instead of their content
• Trainer Directory overhaul -- all registered, non-hidden, non-disabled users now appear in the directory; profile_public gates rich profile details (trainer code, pronouns, location, favourite Pokemon) rather than directory visibility; sorted by online status, staff rank, super-donator status, raid XP, then alphabetically
• Tester role -- new tester role shows "PKMN Scientist" rank label in the Raid Finder and sorts above regular users in the Trainer Directory
• Tag management improvements -- superadmins can now edit existing tags (name and color); tag listing and assignment/removal lowered to moderator level; tags can be assigned to any user

---

Prerequisites

Requirement	Version
Go	1.25+
Node.js + npm	18+
MySQL	8+
Caddy (or other reverse proxy)	2+

---

Setup

1. Clone the repo

git clone https://github.com/Hailey-Ross/hailsDotGO.git
cd hailsDotGO
git checkout v0.1.1a

2. Install frontend dependencies

npm install

3. Configure environment

cp .env.example .env

Edit .env with your values:

Variable	Required	Description
DB_HOST	Yes	MySQL host and port -- e.g. localhost:3306
DB_USER	Yes	MySQL username
DB_PASS	Yes	MySQL password
DB_NAME	Yes	MySQL database name (e.g. hailsdotgo)
SUPERADMIN_USER	Yes	Username that always has full admin privileges
CSRF_KEY	Recommended	64-char hex string -- generate with openssl rand -hex 32
PORT	No	HTTP listen port, default 8080
PAYPAL_CLIENT_ID	Store only	PayPal REST API client ID
PAYPAL_CLIENT_SECRET	Store only	PayPal REST API client secret
PAYPAL_MODE	Store only	sandbox or live
PAYPAL_WEBHOOK_ID	Store only	PayPal webhook ID for payment confirmation

CSRF_KEY is optional but strongly recommended. Without it, CSRF tokens regenerate on every restart and invalidate all active login sessions.

4. Set up the database

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS hailsdotgo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p hailsdotgo < schema.sql

schema.sql creates all tables and seeds the required site_settings rows (all pages default to enabled, registration defaults to closed).

Upgrading from a previous install? Do not re-run the full schema. Instead, uncomment and execute only the migration blocks at the bottom of schema.sql that you have not applied yet.

5. First admin account

Registration is closed on a fresh install. To create your first account:

Option A -- open registration temporarily:

UPDATE site_settings SET setting_value = '1' WHERE setting_key = 'registration_open';

Set SUPERADMIN_USER=yourusername in .env, start the server, register at /register, then close registration from the admin panel.

Option B -- promote via SQL after registering:

UPDATE users SET role = 'admin' WHERE username = 'yourusername';

6. Build

# TypeScript (outputs to static/js/)
npm run build

# Go binary
go build -o hailsDotGO .

Or: make build (runs both).

Cross-compile for Linux from Windows:

$env:GOOS = "linux"; $env:GOARCH = "amd64"; $env:CGO_ENABLED = "0"
go build -ldflags="-s -w" -o hailsDotGO-linux .

7. Run locally

# Terminal 1 -- recompile TypeScript on save
npm run watch

# Terminal 2 -- Go server
go run .

Visit http://localhost:8080

---

Server Deployment (Linux / systemd)

Create service user and directory

sudo useradd --system --no-create-home --shell /usr/sbin/nologin hailsdotgo
sudo mkdir -p /opt/hailsdotgo
sudo chown hailsdotgo:hailsdotgo /opt/hailsdotgo

Copy files to the server

/opt/hailsdotgo/hailsDotGO     <- compiled Linux/amd64 binary
/opt/hailsdotgo/app.env        <- your .env (chmod 600, owned by hailsdotgo)
/opt/hailsdotgo/templates/     <- all .html files from templates/
/opt/hailsdotgo/static/        <- static/ directory (css, js, sprites)

Install and start the service

A ready-made unit file is included at deploy/hailsdotgo.service:

sudo cp deploy/hailsdotgo.service /etc/systemd/system/hailsdotgo.service
sudo systemctl daemon-reload
sudo systemctl enable hailsdotgo
sudo systemctl start hailsdotgo

The service runs as the hailsdotgo user, loads environment from /opt/hailsdotgo/app.env, and restarts automatically on failure.

---

Reverse Proxy (Caddy)

A sample Caddyfile is included at deploy/Caddyfile. The relevant block:

yourdomain.com {
    encode gzip zstd
    reverse_proxy localhost:8080
}

Replace yourdomain.com with your actual domain. Caddy provisions HTTPS automatically via Let's Encrypt.

sudo systemctl reload caddy

---

Optional: Supporter Store

The store is disabled by default. To enable it:

1. Set the four PAYPAL_* variables in app.env.
2. Enable from the admin panel, or directly:

   UPDATE site_settings SET setting_value = '1' WHERE setting_key = 'store_enabled';

3. Run the store migration block in schema.sql (seeds store_items and purchases tables with two default items).

---

Data Sources

Source	What it provides
PoGoAPI	Pokemon stats, moves, shinies, type effectiveness, CP multipliers
ScrapedDuck	Live raid boss data (sourced from LeekDuck)
PokeAPI	Pokemon sprites, Pokedex text, genus, legendary flags, cries
Open-Meteo	Weather data for GO weather boost detection (no API key required)
Pokemon Showdown	Trainer class sprites for profile avatars
Dreamstone Mysteries	GBA-style trainer sprites (bundled as local static files)