jfberry · jfberry · May 29, 2026 · May 30, 2026 · May 30, 2026 · May 30, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -26,7 +26,7 @@ jobs:
       run:
         working-directory: processor
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v6

diff --git a/API.md b/API.md
@@ -2,6 +2,10 @@
 
 All API endpoints are available through the processor (default port 3030). The processor handles all endpoints directly.
 
+> **Live OpenAPI docs.** This surface is now also documented live via an OpenAPI 3.1 spec at `GET /openapi.json` with interactive docs at `GET /docs` (both public, no secret). The `/api/*` read/feature endpoints are served by [huma](https://github.com/danielgtaylor/huma), and errors on the huma surface are returned as RFC 9457 `application/problem+json` (`status`, `title`, `detail`, `errors[]`) rather than the legacy `{status:"error",message}` shape shown under [Response Format](#response-format).
+>
+> **New strict `/api/v2` API.** A clean, strict, typed `/api/v2` surface (human-scoped tracking — including the new `incident` type — plus discrete humans/profiles action endpoints) is the **recommended API for new clients**. The v1 endpoints documented below are **frozen and deprecated-but-supported** (no sunset date yet); migrate to `/api/v2` to access new tracking types and the cleaner contract. See the [v1 → v2 migration guide](docs/v1-to-v2-migration-guide.md) for the endpoint/field mapping, and [`docs/v2-api-design.md`](docs/v2-api-design.md) and `/docs` for v2 details.
+
 ## Contents
 
 - [Authentication](#authentication)
@@ -329,8 +333,8 @@ Use `level: 90` for all levels.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `reward_type` | int | required | Reward type (2=item, 3=stardust, 4=candy, 7=pokemon, 12=mega energy) |
-| `reward` | int | 0 | Reward ID (pokemon ID, item ID, or stardust amount) |
+| `reward_type` | int | required | Reward type (2=item, 3=stardust, 4=candy, 7=pokemon, 8=pokecoins, 12=mega energy) |
+| `reward` | int | 0 | Reward ID (pokemon ID, item ID, or stardust/pokecoin amount) |
 | `form` | int | 0 | Form ID (for pokemon rewards) |
 | `shiny` | bool | false | Shiny only |
 | `amount` | int | 0 | Minimum reward amount |
@@ -1041,7 +1045,7 @@ Returns test webhook scenarios from `testdata.json`. The editor can use these as
 }
 ```
 
-Available test scenarios: boring, hundo, great-rank1, great-rank9, ultra1, unencountered, boosted, shiny (pokemon); egg1, level1, egg5, level5, egg6, level3 (raid); invasion, lure, giovanni, kecleon, goldstop, goldlure, showcase, pokemoncontest (pokestop); teamchange (gym); level1, level3 (max_battle); quest-item, quest-stardust, quest-pokemon, quest-energy (quest); edit, new, remove, etc. (fort_update).
+Available test scenarios: boring, hundo, great-rank1, great-rank9, ultra1, unencountered, boosted, shiny (pokemon); egg1, level1, egg5, level5, egg6, level3 (raid); invasion, lure, giovanni, kecleon, goldstop, goldlure, showcase, pokemoncontest (pokestop); teamchange (gym); level1, level3 (max_battle); quest-item, quest-stardust, quest-pokecoins, quest-pokemon, quest-energy (quest); edit, new, remove, etc. (fort_update).
 
 ### GET/POST /api/dts/reload
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to PoracleNG are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- **v2 mutes API.** `GET/POST /api/v2/humans/{id}/mutes` and
+  `DELETE /api/v2/humans/{id}/mutes[?scope=&value=]` expose the in-memory alert
+  mutes (the `!mute` / alert-button feature) over HTTP, and the v2 full
+  snapshot now carries a `mutes` array. Mutes remain volatile — they are
+  cleared by a processor restart.
+- **OpenAPI 3.1 spec + interactive docs.** The processor now serves a single
+  OpenAPI 3.1 document at `GET /openapi.json` with interactive documentation at
+  `GET /docs` (both public, no `X-Poracle-Secret` required). The spec covers the
+  entire `/api/*` and `/api/v2/*` surface, generated from the code via
+  [huma](https://github.com/danielgtaylor/huma) mounted on gin.
+- **New strict `/api/v2` API** for tracking and humans/profiles — typed bodies,
+  `additionalProperties: false`, enforced required fields, and no lenient type
+  coercion. A malformed request gets a clear `422` instead of a silent guess.
+  - **Tracking** is human-scoped: `GET|POST /api/v2/humans/{id}/tracking/{type}`,
+    `GET|PUT|DELETE /api/v2/humans/{id}/tracking/{type}/{uid}`, bulk
+    `DELETE …/{type}?uid=1,2,3`, and a full snapshot at
+    `GET /api/v2/humans/{id}/tracking` (human + all-type rules + profiles +
+    locations + summaries). Supports `?profile=`, `?include_descriptions=`,
+    `?silent=`, and `?all_profiles=`.
+  - **humans/profiles** are exposed as discrete, typed action endpoints under
+    `/api/v2/humans/{id}/…` (enable/disable, admin-disable, language, location,
+    areas, check-location, locations CRUD, roles, profiles CRUD with a strict
+    typed `active_hours` schema, and profile switch).
+- **New `incident` tracking type** (game `PokestopEvent`, e.g. Showcase) —
+  available only via the `/api/v2` tracking surface, bringing the v2 tracking
+  type count to 11 (pokemon, raid, egg, quest, invasion, incident, lure, nest,
+  gym, fort, maxbattle).
+- **New `PUT /api/v2/humans/{id}/locations/{label}`** — update a saved
+  location's coordinates in place, completing saved-location CRUD (v1 required
+  delete + re-add to move a location).
+
+### Changed
+
+- **Error bodies on the huma `/api` surface are now RFC 9457
+  `application/problem+json`** (`status`, `title`, `detail`, `errors[]`),
+  replacing the old ad-hoc `{ "status": "error", "message": … }` /
+  `{ "error": … }` bodies. **This is a behavior change for clients that parse
+  error response bodies.** HTTP status codes are unchanged, though a few
+  input-validation failures that were manual `400`s now surface as huma
+  validation `422`s.
+- **`include_empty` on fort tracking now defaults to `true`** when omitted,
+  honoring the `forts` DB column default. The previous gin handler defaulted it
+  to `false`; API clients that omit `include_empty` now get `true`.
+
+### Deprecated
+
+- **v1 tracking/humans/profiles endpoints are frozen and
+  deprecated-but-supported.** `/api/tracking/*`, `/api/humans/*`,
+  `/api/profiles/*` (and `/api/tracking/pokemon/refresh`) remain on gin,
+  unchanged and fully functional — clients migrate to `/api/v2` on their own
+  schedule. Migration is encouraged to access new tracking types (e.g.
+  `incident`) and the cleaner strict contract. No sunset date is set yet.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -343,6 +343,10 @@ Role-loss handling is left to Discord: private-thread visibility inherits View C
 - `GET /health` — health check
 - `GET /metrics` — Prometheus metrics
 - `POST /` — webhook receiver from Golbat (no auth, Golbat doesn't authenticate)
+- `GET /openapi.json` — OpenAPI 3.1 spec
+- `GET /docs` — interactive API docs
+
+**huma surface (`/api/*` reads + features, and `/api/v2/*`)**: The `/api/*` read/reload/feature endpoints listed below and the entire `/api/v2/*` surface are served by [huma](https://github.com/danielgtaylor/huma) (mounted on gin via humagin, one instance), and appear in the OpenAPI 3.1 spec at `/openapi.json` / `/docs`. Error bodies on this surface are RFC 9457 `application/problem+json` (`status`, `title`, `detail`, `errors[]`) — replacing the old `{status:"error",message}` / `gin.H{"error":...}` bodies (status codes unchanged; a few manual-400s became validation-422s). `/health`, `/metrics`, pprof, and the webhook receiver `POST /` stay on plain gin by design.
 
 ## Command System
 
@@ -543,11 +547,20 @@ All API endpoints are accessed via the processor (port 3030). The processor hand
 | DELETE | `/api/profiles/{id}/byProfileNo/{profile_no}` | Delete profile |
 | GET | `/api/snapshots/{messageID}?target={id}` | Inspect a delivered-message snapshot (admin diagnostics; 503 if `[snapshots] enabled = false`) |
 | GET | `/api/dts/actions` | List registered button actions + their scopes/params (drives the config editor's button UI) |
-| GET | `/health` | Health check; returns `{status, version, capabilities}` where `capabilities` is a static feature map (`buttons`, `snapshots`, `autocreate`, `tomlDts`, `buttonResponseObject`) so clients can do explicit feature detection without probing endpoints |
+| GET | `/health` | Health check; returns `{status, version, capabilities}` where `capabilities` is a static feature map (`buttons`, `snapshots`, `autocreate`, `tomlDts`, `buttonResponseObject`, `derivedDtsTypes`) so clients can do explicit feature detection without probing endpoints |
 | GET | `/metrics` | Prometheus metrics |
+| GET | `/openapi.json` | OpenAPI 3.1 spec (whole `/api` + `/api/v2` surface; public) |
+| GET | `/docs` | Interactive API docs (public) |
 
 Tracking types: pokemon, raid, egg, quest, invasion, lure, nest, gym, fort, maxbattle.
 
+**`/api/v2/*` (strict v2 surface)**: Alongside the in-place `/api/*` endpoints above sits a clean, strict, documented v2 API for tracking + humans/profiles. It is served by the same huma instance (typed bodies, `additionalProperties:false`, no lenient coercion, problem+json errors).
+- **Tracking** is human-scoped: `GET|POST /api/v2/humans/{id}/tracking/{type}`, `GET|PUT|DELETE /api/v2/humans/{id}/tracking/{type}/{uid}`, bulk `DELETE …/{type}?uid=1,2,3`, and a full snapshot `GET /api/v2/humans/{id}/tracking` (human + all-type rules + profiles + locations + summaries). Query params: `?profile=`, `?include_descriptions=`, `?silent=`, `?all_profiles=`. v2 adds an **11th tracking type, `incident`** (game `PokestopEvent`, e.g. Showcase), not present in v1.
+- **humans/profiles** are discrete typed action endpoints under `/api/v2/humans/{id}/…` (enable/disable, admin-disable, language, location, areas, check-location, locations CRUD incl. a **new `PUT …/locations/{label}`** to update coords, roles, profiles CRUD with a strict typed `active_hours` schema, profile switch). Pure action endpoints return a minimal `{"status":"ok"}` ack; resource endpoints return the typed body directly.
+- Design doc: `docs/v2-api-design.md`.
+
+**v1 is frozen**: the v1 `/api/tracking/*`, `/api/humans/*`, `/api/profiles/*` (and `/api/tracking/pokemon/refresh`) endpoints remain on plain gin, unchanged and fully supported (still lenient via the coercion below), but deprecated — clients migrate to `/api/v2` on their own schedule. No sunset date yet.
+
 **Flexible JSON type coercion**: All tracking CRUD POST endpoints accept flexible JSON types for numeric and boolean fields. Third-party clients like ReactMap may send `"clean": false` (boolean) instead of `"clean": 0` (number). The `flexBool` and `flexInt` custom JSON types in `processor/internal/api/tracking.go` handle this coercion transparently:
 - `flexBool`: accepts `true`/`false`, `0`/`1`, `"0"`/`"1"` — coerces to int (0 or 1)
 - `flexInt`: accepts numbers, booleans, quoted strings — coerces to int
@@ -702,8 +715,9 @@ The store is a separate pogreb instance from the geocoder cache — different wo
 - `!<type> mute ...` aliases (e.g. `!raid mute id:X`) route through `RouteToMuteFromType`.
 - `!tracked` shows the active mutes alongside tracking rules.
 - Mute buttons on alerts (see "Button actions" below) write the same `mute.Entry` shape via `buttonactions.HandleMute`.
+- **v2 mutes API** (`internal/api/v2_mutes.go`): `GET|POST /api/v2/humans/{id}/mutes`, `DELETE …/mutes?scope=&value=` (single) and `DELETE …/mutes` (all). Strict schemas, problem+json; mute identity is `(scope, value)` so deletes address via query params; DELETE returns `{deleted:[…]}` like v2 tracking. Area values validate against `AreaLogic` when present, else live `StateMgr` fences (production path). The v2 full snapshot includes a `mutes` array. The API documents the in-memory volatility — entries vanish on restart. Design: `docs/superpowers/specs/2026-06-11-mute-api-design.md`.
 
-Tracking-UID mutes (`!mute id:N` / `!mute raid id:N`) are documented in the design but rejected by the v1 parser — they need `MatchedUser.RuleUID` plumbing in the matcher first.
+Tracking-UID mutes are fully wired: the matcher compares `mute.Event.MatchedRuleUID` (populated per matched user in `cmd/processor/helpers.go`) against `tracking`-scope entries, created via `!mute id:N`, alert buttons, or the v2 mutes API.
 
 ## Button Actions
 

diff --git a/DTS.md b/DTS.md
@@ -210,6 +210,7 @@ These fields are available in every template:
 | `neighbourhood` | string | Neighbourhood name |
 | `suburb` | string | Suburb name |
 | `flag` | string | Country flag emoji |
+| `intersection` | string | Nearest street intersection (`Street1 & Street2`) from GeoNames; empty when disabled (`[geocoding] intersection_users`) or none nearby |
 | `staticMap` | string | Static map tile image URL |
 | `staticmap` | string | *Deprecated* — alias for `staticMap` |
 | `imgUrl` | string | Primary icon URL |
@@ -420,9 +421,12 @@ Time-remaining fields (`tthd`, `tthh`, `tthm`, `tths`) are in the Common Fields
 | `megaEvolutions` | array | Mega evolution entries |
 | `hasMegaEvolutions` | bool | Has mega evolutions |
 | `pokestopName` | string | Nearby pokestop name (if applicable) |
+| `costumeName` | string | Translated costume name (empty when no costume, i.e. `costume == 0` or the `costume_N` translation key is absent). |
 
 `distance`, `bearing`, `bearingEmoji`, `userDistanceTrack`, `userTrackDistance` are documented in Common Fields.
 
+**Note:** `fullName` already includes the costume, parenthesised, when the pokemon is wearing one — e.g. `"Pikachu (Holiday 2016)"`. `costumeName` is provided separately for templates that want to style or place the costume text independently of `fullName`.
+
 ### seenType values
 
 `{{seenType}}` is normalised from Golbat's raw `seen_type` (see Golbat's
@@ -719,13 +723,17 @@ See `examples/dts/rsvpChanges/rsvp-update.json` for an installable starting poin
 | `pokestopUrl` | string | Pokestop image URL (alias for `pokestop_url`) |
 | `questString` | string | Translated quest objective |
 | `questStringEng` | string | English quest objective |
+| `quest_task` | string | Legacy PoracleJS alias for `questString` (translated objective) |
 | `rewardString` | string | All rewards as text (translated) |
 | `rewardStringEng` | string | English rewards text |
+| `quest_reward` | string | Legacy PoracleJS alias for `rewardString` |
 | `conditionString` | string | Comma-joined completion conditions, translated, e.g. "Excellent Throw, Curve Ball" |
 | `conditionStringEng` | string | English copy of `conditionString` |
+| `quest_conditions` | string | Legacy PoracleJS alias for `conditionString` |
 | `conditionList` | array | Per-condition objects: `{type, name, formatted}` where `name` is the bare label ("Throw Type") and `formatted` includes the payload ("Excellent Throw"). Falls back to bare name when the webhook payload doesn't carry the data needed for the formatted variant. |
 | `conditionListEng` | array | English copy of `conditionList` |
 | `dustAmount` | int | Stardust reward amount |
+| `pokecoinAmount` | int | Pokecoin reward amount |
 | `itemAmount` | int | Item reward amount |
 | `energyAmount` | int | Mega energy amount (first reward) |
 | `candyAmount` | int | Candy amount (first reward) |
@@ -757,6 +765,8 @@ These are flat top-level strings, not nested under a `rewardData` object:
 | `itemNamesEng` | string | English item names |
 | `dustText` | string | Translated stardust text (e.g. "500 Stardust") |
 | `dustTextEng` | string | English stardust text |
+| `pokecoinText` | string | Translated pokecoin text (e.g. "10 Pokécoins") |
+| `pokecoinTextEng` | string | English pokecoin text |
 | `energyMonstersNames` | string | Mega energy reward text (translated) |
 | `energyMonstersNamesEng` | string | English energy reward text |
 | `candyMonstersNames` | string | Candy reward text (translated) |
@@ -777,7 +787,7 @@ The view passed to `questSummary` is shaped differently from a regular `quest` t
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `rewardType` | int | Reward type ID (2=item, 3=stardust, 4=candy, 7=pokemon, 12=mega energy) |
+| `rewardType` | int | Reward type ID (2=item, 3=stardust, 4=candy, 7=pokemon, 8=pokecoins, 12=mega energy) |
 | `reward` | int | Reward ID (item ID for type 2, dust amount for type 3, pokemon ID for types 4/7/12) |
 | `rewardForm` | int | Pokemon form ID for `rewardType == 7` (so e.g. two different Spinda forms group separately). `0` for all other reward types. |
 | `rewardName` | string | Translated reward name for the group header. Formatted to match the per-row reward strings from regular `quest` enrichment, **with amounts stripped** for types 2/4/12 because amounts vary across stops within a group. Examples: `"Spinda 01"` (type 7 + form, matches per-row `fullName`), `"Lapras Candy"` (type 4), `"Charizard Mega Energy"` (type 12), `"Razz Berry"` (type 2), `"1500 Stardust"` (type 3 — amount is included because it's part of the group key). |
@@ -862,7 +872,11 @@ These aliases are added on top of the pokestop / location / time / weather field
 
 ### Showcase fields
 
-These fields are only populated for **Showcase** incidents (`displayType == 9`). Always guard showcase blocks with `{{#if showcasePresent}}`.
+**Showcases render via their own `type: "showcase"` template** — a specialised display model (focus + leaderboard), distinct from the plain `incident` card used by Gold-Stop / Kecleon. A bundled default `showcase` template ships in `fallbacks/dts.json`; operators can override it like any other type. (Showcases are still *tracked* as incidents — a `grunt_type="showcase"` incident rule — only the rendered template differs.)
+
+The `showcase` type resolves the pokestop-identity / time / `displayType` fields (shared with `incident`) **plus** the showcase fields below. It does **not** carry the incident-only aliases `incidentTypeName`, `incidentEmoji`, or `color` — the bundled template hardcodes its title/emoji/colour, so those render empty if used in a showcase template.
+
+Always guard the leaderboard with `{{#if showcasePresent}}` and the focus line with `{{#if showcaseFocusPresent}}`.
 
 #### Top-level showcase fields
 
@@ -874,6 +888,13 @@ These fields are only populated for **Showcase** incidents (`displayType == 9`).
 | `showcaseLastUpdateFormatted` | string | `showcaseLastUpdate` formatted using the operator's configured time layout. |
 | `showcase` | array | Up to 3 enriched contestant entries (see per-entry fields below). Empty array when no data. |
 | `showcaseFirst` | object | Convenience alias for `showcase[0]` (the winner). `nil` when no contestants. |
+| `showcaseFocusPresent` | bool | `true` when the contest's featured focus was decoded. Guard focus blocks with `{{#if showcaseFocusPresent}}`. |
+| `showcaseFocusType` | string | Raw focus class: `pokemon`, `type`, `alignment`, `class`, `family`, `buddy`, `generation`, `hatched`, `mega`, `shiny`. |
+| `showcaseFocusCategory` | string | Translated focus category label, e.g. `Type`, `Buddy`. |
+| `showcaseFocusName` | string | Translated featured value, e.g. `Steel` (type focus) or `3+` (buddy focus). Empty for flag focuses (`hatched`/`shiny`/`mega`) — the category conveys it. |
+| `showcaseFocusEmoji` | string | Optional emoji key for the focus category (from `util.json` `showcaseFocus`). |
+
+The focus tells you *what the contest is featuring* (e.g. "Type: Steel"), separate from the `showcase` leaderboard of *who is winning*. Example: `{{#if showcaseFocusPresent}}Featuring {{showcaseFocusCategory}}: {{showcaseFocusName}}{{/if}}`.
 
 #### Per-entry fields (each item in `{{#each showcase}}`)