From 88e9e88f46275c727b09a7ee78c0594630f4bbbd Mon Sep 17 00:00:00 2001
From: Erik <erik.nihlen@gmail.com>
Date: Sat, 25 Apr 2026 23:07:57 +0200
Subject: [PATCH] docs(agent): brief Claude on AC rare tier classification
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The user kept asking 'show me great rares' and Claude kept showing
Crystals/Pearls/Jewels because the rare_events table doesn't store the
tier — and Claude didn't know the distinction. Now CLAUDE.md spells out
the ~71-item common allowlist (matching discord-rare-monitor's regex)
plus example great-rare names. Includes a sample SQL query Claude can
adapt for tier filtering.
---
 CLAUDE.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index dbc80299..33099b0c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -179,6 +179,39 @@ You are a **read-only game-state question-answering service**. Nothing more.
 6. **Suitbuilder** is a separate complex tool that runs constraint search; explain trade-offs in plain English when reporting results.
 7. **Out-of-scope questions** (general AC lore, unrelated coding) — answer briefly without using tools.
 
+### Rare tiers — important domain knowledge
+
+Asheron's Call players distinguish two rare tiers, but our `rare_events`
+table does **not** store the tier — only the item `name`. To answer
+"what are the recent great rares" or "filter common vs great", classify
+in your head from the name:
+
+**Common rares** (the ~71-item allowlist used by `discord-rare-monitor`):
+- Anything ending in `'s Crystal` (Alchemist's Crystal, Knight's Crystal, etc.)
+- `Lugian's/Ursuin's/Wayfarer's/Sprinter's/Magus's/Lich's Pearl`
+- All `*'s Jewel` (Warrior's, Mage's, Duelist's, Archer's, Tusker's, Olthoi's, Inferno's, Gelid's, Astyrrian's, Executor's, Melee's)
+- `Pearl of <Effect>` (Blood Drinking, Heart Seeking, Defending, Swift Killing, Spirit Drinking, Hermetic Linking, Blade/Pierce/Bludgeon/Acid/Flame/Frost/Lightning Baning, Impenetrability)
+- `Refreshing/Invigorating/Miraculous Elixir`, `Medicated Health/Stamina/Mana Kit`
+- `Casino Exquisite Keyring`
+
+**Great rares** = anything else dropped from a rare event. Examples include:
+- `Shimmering Skeleton Key`, `Star of Tukal`
+- `Hieroglyph/Pictograph/Ideograph/Rune of …`
+- `Infinite/Eternal/Perennial/Foolproof/Limitless …`
+- `Gelidite`, `Leikotha`, `Frore` items
+- `Staff of …`, `Wand of …`, `Count Renari's …`
+
+When the user asks about "great rares", filter `get_recent_rares` results
+by the name NOT matching the common list, or run a SQL query like:
+```sql
+SELECT timestamp, character_name, name FROM rare_events
+ WHERE timestamp >= NOW() - INTERVAL '7 days'
+   AND name !~ '(Crystal|Jewel|Elixir|Kit|Keyring)$'
+   AND name NOT LIKE 'Pearl of %'
+   AND name !~ '(Lugian|Ursuin|Wayfarer|Sprinter|Magus|Lich)''s Pearl'
+ ORDER BY timestamp DESC;
+```
+
 ### Available data tables (for `query_telemetry_db`)
 
 - `telemetry_events` (hypertable, 30-day retention) — position/state snapshots every ~2s per character