feat(ai): inline wowhead links across every prose section

Today's analysis card has Wowhead-tooltip chips clipped under each
finding's prose — and the rotation / cooldown / talent / gear /
comparison sections have no links at all even though their prose
frequently names spells/items/talents. This adds inline links to every
prose surface without letting the AI write actual Wowhead URLs.

How
- Prompt: every spell / item / talent reference in any prose field
  (findings.detail, rotation_summary, cooldown_usage_summary,
  stat_recommendations, talent_recommendations, gear_and_trinket_notes,
  comparison_to_top_logs, headline, strengths) MUST be written as a
  markdown link ``[Label](kind:id)``. Three kinds: ``spell``, ``item``,
  ``talent``. Names come from ``localized_names``, IDs from the existing
  data fields. Same EN + DE wording.
- Backend: new ``_collect_talent_spell_ids`` helper resolves the
  ``TraitNodeEntry.ID → SpellID`` mapping from ``wow_localizations.
  extras['spell_id']`` (populated by ``_import_talents``) for every
  talent id that appears in the player or any reference. Stitched into
  the analysis's structured output as ``_talent_spell_ids`` so the
  frontend can turn ``talent:<id>`` markdown into a proper /spell/<id>
  Wowhead URL — talent ids collide with old MoP spell ids, so a naïve
  link would 404 onto an unrelated MoP spell.
- Frontend: new ``ProseWithLinks`` component parses
  ``[Label](kind:id)`` with a strict regex and substitutes SpellLink /
  ItemLink / SpellLink-via-talent-map components. Renders as
  ``<span class="block">`` so it can sit inside ``<h2>`` (headline) and
  block contexts equally well. Used in every prose surface of
  ``AnalysisCard``.
- Chip-list fallback: still shown on each finding when the prose has
  no inline refs at all (legacy analyses). Hidden once any inline
  markdown link is present in the prose, so users don't see both the
  link and a redundant chip below.

Regex verified against typical AI outputs:
- single inline link → matches
- multiple per line → all matches
- legacy plain prose → no false positives
- malformed markdown → graceful (just renders as text)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: babatonga

backend/app/services/ai/analyzer.py

@@ -20,6 +20,7 @@
     ReportPlayer,
     ReportPlayerCast,
     TopLog,
+    WowLocalization,
 )
 from app.services.ai.anthropic_provider import AnthropicProvider
 from app.services.ai.base import AiProvider, AiResponse
@@ -548,6 +549,55 @@ async def _collect_localized_names(
     return names
 
 
+async def _collect_talent_spell_ids(
+    session: AsyncSession,
+    *,
+    player_summary: dict[str, Any],
+    references: list[dict[str, Any]],
+) -> dict[str, int]:
+    """Build a ``{TraitNodeEntry.ID: SpellID}`` map for every talent ID
+    that appears in the player_summary or any top-log reference detail.
+
+    Frontend uses this to turn ``[Label](talent:<id>)`` inline markdown
+    links into real Wowhead spell links — the TraitNodeEntry IDs WCL
+    ships collide with old MoP-era spell IDs, so we have to resolve
+    through ``wow_localizations.extras['spell_id']`` (populated by
+    ``_import_talents``) before linking. Missing entries silently fall
+    back to bold text on the frontend.
+    """
+    talent_ids: set[int] = set()
+    for tid in player_summary.get("talent_ids") or []:
+        if tid:
+            talent_ids.add(int(tid))
+    for ref in references:
+        for tid in (ref.get("detail") or {}).get("talent_ids") or []:
+            if tid:
+                talent_ids.add(int(tid))
+    if not talent_ids:
+        return {}
+    # One row per talent (en locale — extras['spell_id'] is locale-
+    # agnostic). UNIQUE constraint on (kind, game_id, locale) means
+    # we only ever get one row per ID.
+    rows = (
+        await session.execute(
+            select(WowLocalization.game_id, WowLocalization.extras)
+            .where(WowLocalization.kind == "talent")
+            .where(WowLocalization.locale == "en")
+            .where(WowLocalization.game_id.in_(talent_ids))
+        )
+    ).all()
+    out: dict[str, int] = {}
+    for game_id, extras in rows:
+        spell_id = (extras or {}).get("spell_id")
+        if not spell_id:
+            continue
+        try:
+            out[str(int(game_id))] = int(spell_id)
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
 async def request_analysis(
     session: AsyncSession,
     *,
@@ -821,6 +871,9 @@ def _annotate_damage_taken(
         gear=gear,
         references=references,
     )
+    talent_spell_ids = await _collect_talent_spell_ids(
+        session, player_summary=player_summary, references=references
+    )
 
     # If the row already exists (worker path), it tells us whether BYOK was
     # requested. New rows fall through to the app-wide path.
@@ -915,6 +968,11 @@ def _annotate_damage_taken(
         analysis.structured = {
             **(response.structured or {}),
             "_localized_names": localized_names,
+            # ``[Label](talent:<id>)`` markdown links in the AI's prose
+            # carry TraitNodeEntry IDs (different namespace from spell
+            # IDs). Frontend resolves to the underlying spell ID via
+            # this map before linking to Wowhead.
+            "_talent_spell_ids": talent_spell_ids,
             "_parse_metrics": {
                 "parse_percent": parse_metrics.get("rank_percent"),
                 "ilvl_percent": parse_metrics.get("ilvl_percent"),

backend/app/services/ai/prompts.py

@@ -82,6 +82,27 @@ def stat_glossary_for(locale: Locale) -> dict[str, str]:
   buff/debuff uptime percentages, and damage/healing totals from the JSON.
 - For every finding, name the spell(s) or item(s) involved by spell ID / item
   ID (so the UI can render Wowhead tooltips).
+- **EVERY mention of a spell, item or talent in your prose MUST be written
+  as an inline markdown link in the form ``[Label](kind:id)``** — the
+  frontend parses these and renders them as Wowhead tooltip-aware links.
+  This applies to ``findings[*].detail``, ``rotation_summary``,
+  ``cooldown_usage_summary``, ``stat_recommendations``,
+  ``talent_recommendations``, ``gear_and_trinket_notes``,
+  ``comparison_to_top_logs``, ``headline`` and every entry of
+  ``strengths``. Three valid forms:
+
+      [Mana Tea](spell:115294)            — buffs, casts, debuffs, boss abilities
+      [Algari Mana Potion](item:212017)   — consumables, trinkets, gear
+      [Tea Time](talent:124683)           — talent-tree picks from talent_ids
+
+  ``Label`` is the localised name (use ``localized_names`` verbatim — never
+  invent translations). ``id`` is the numeric ID exactly as it appears in
+  the relevant key of ``localized_names`` / ``talent_ids`` / the gear's
+  ``item_id`` / the cast's ``ability_id``. Do **not** write a plain spell
+  name without the ``[…](spell:…)`` wrapper, do **not** emit raw Wowhead
+  URLs yourself, and do **not** invent IDs that don't appear in the data.
+  When you genuinely need to refer to an ability whose ID isn't in the
+  data, write ``the ability "X"`` in plain text — no link.
 - Compare the player's casts, buff uptimes, and gear against the supplied
   top-log reference players (same spec, same encounter, same region, same
   difficulty). Call out concrete deltas:
@@ -257,6 +278,28 @@ def stat_glossary_for(locale: Locale) -> dict[str, str]:
   Prozente, Damage-/Healing-Summen aus dem JSON.
 - Bei jedem Befund die betroffenen Zauber/Items per Spell-ID / Item-ID
   benennen, damit die UI Wowhead-Tooltips rendern kann.
+- **JEDE Erwähnung eines Zaubers, Items oder Talents in deinem Fließtext
+  MUSS als inline Markdown-Link in der Form ``[Label](kind:id)``
+  geschrieben werden** — das Frontend parst diese und rendert sie als
+  Wowhead-Tooltips. Gilt für ``findings[*].detail``, ``rotation_summary``,
+  ``cooldown_usage_summary``, ``stat_recommendations``,
+  ``talent_recommendations``, ``gear_and_trinket_notes``,
+  ``comparison_to_top_logs``, ``headline`` und jeden Eintrag von
+  ``strengths``. Drei gültige Formen:
+
+      [Mana-Tee](spell:115294)            — Buffs, Casts, Debuffs, Boss-Fähigkeiten
+      [Algari-Manatrank](item:212017)     — Verbrauchsgüter, Trinkets, Ausrüstung
+      [Teezeit](talent:124683)            — Talente aus talent_ids
+
+  ``Label`` ist der lokalisierte Name (nutze ``localized_names`` verbatim
+  — übersetze nichts selbst). ``id`` ist die numerische ID exakt wie sie
+  im jeweiligen Schlüssel von ``localized_names`` / ``talent_ids`` / im
+  ``item_id`` des Gears / im ``ability_id`` des Casts steht. Schreib
+  **keinen** plain Zaubernamen ohne ``[…](spell:…)``-Wrapper, gib
+  **keine** rohen Wowhead-URLs aus, und **erfinde keine** IDs die nicht
+  in den Daten stehen. Wenn du wirklich eine Fähigkeit erwähnen musst,
+  deren ID nicht in den Daten ist, schreib „die Fähigkeit X" als
+  Plaintext — kein Link.
 - Casts, Buff-Uptimes und Ausrüstung des Spielers gegen die mitgelieferten
   Top-Log-Referenzspieler (gleiche Spec, gleicher Boss, gleiche Region,
   gleiche Schwierigkeit) vergleichen. Konkrete Deltas nennen:

frontend/src/components/AnalysisCard.tsx

@@ -5,6 +5,7 @@ import { useEffect, useMemo } from "react";
 
 import { Card } from "@/components/ui";
 import { ItemLink } from "@/components/ItemLink";
+import { ProseWithLinks, hasInlineRefs } from "@/components/ProseWithLinks";
 import { SeverityBadge } from "@/components/SeverityBadge";
 import { SpellLink } from "@/components/SpellLink";
 import { formatPercent } from "@/lib/format";
@@ -26,6 +27,12 @@ export function AnalysisCard({ analysis, locale }: Props) {
   // for the spell/item chips even when ad blockers stop wowhead's tooltip
   // script from auto-renaming the link.
   const nameMap = structured._localized_names ?? {};
+  // ``_talent_spell_ids`` is the per-analysis lookup the backend ships so
+  // we can render ``[Label](talent:<traitNodeEntryId>)`` markdown links
+  // as Wowhead spell links. WCL ships TraitNodeEntry IDs which collide
+  // with old MoP spell IDs, so we MUST resolve to the underlying spell
+  // ID before linking.
+  const talentSpellIds = structured._talent_spell_ids ?? {};
   const parseMetrics = structured._parse_metrics;
 
   // Wowhead's tooltip script (loaded once at the layout level) only scans
@@ -88,7 +95,15 @@ export function AnalysisCard({ analysis, locale }: Props) {
     <div className="space-y-4">
       <Card>
         <div className="flex flex-wrap items-baseline justify-between gap-3">
-          <h2 className="text-xl font-semibold">{s.headline ?? "—"}</h2>
+          <h2 className="text-xl font-semibold">
+            <ProseWithLinks
+              text={s.headline ?? "—"}
+              locale={locale}
+              nameMap={nameMap}
+              talentSpellIds={talentSpellIds}
+              className=""
+            />
+          </h2>
           <div className="flex flex-wrap items-baseline gap-2">
             {parseMetrics?.parse_percent !== null && parseMetrics?.parse_percent !== undefined ? (
               <span
@@ -169,8 +184,19 @@ export function AnalysisCard({ analysis, locale }: Props) {
                 )}
               </div>
               <h4 className="mt-2 text-base font-semibold text-zinc-100">{f.title}</h4>
-              <p className="mt-1 whitespace-pre-line text-sm text-zinc-200">{f.detail}</p>
-              {f.related_spell_ids?.length || f.related_item_ids?.length ? (
+              <ProseWithLinks
+                text={f.detail}
+                locale={locale}
+                nameMap={nameMap}
+                talentSpellIds={talentSpellIds}
+                className="mt-1 text-sm text-zinc-200"
+              />
+              {/* Chip list only as a fallback for legacy analyses without
+                  inline markdown links in their prose — modern outputs
+                  render the links inline above and the chips become
+                  redundant. */}
+              {!hasInlineRefs(f.detail) &&
+              (f.related_spell_ids?.length || f.related_item_ids?.length) ? (
                 <div className="mt-2 flex flex-wrap gap-2 text-xs">
                   {f.related_spell_ids?.map((id) => (
                     <SpellLink
@@ -196,12 +222,12 @@ export function AnalysisCard({ analysis, locale }: Props) {
       </Card>
 
       <div className="grid gap-4 md:grid-cols-2">
-        {textBlock(t("analyze.rotation"), s.rotation_summary)}
-        {textBlock(t("analyze.cooldowns"), s.cooldown_usage_summary)}
-        {textBlock(t("analyze.stats"), s.stat_recommendations)}
-        {textBlock(t("analyze.talents"), s.talent_recommendations)}
-        {textBlock(t("analyze.gearTrinkets"), s.gear_and_trinket_notes)}
-        {textBlock(t("analyze.comparison"), s.comparison_to_top_logs)}
+        {proseBlock(t("analyze.rotation"), s.rotation_summary, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.cooldowns"), s.cooldown_usage_summary, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.stats"), s.stat_recommendations, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.talents"), s.talent_recommendations, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.gearTrinkets"), s.gear_and_trinket_notes, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.comparison"), s.comparison_to_top_logs, locale, nameMap, talentSpellIds)}
       </div>
     </div>
   );
@@ -211,12 +237,23 @@ function severityRank(s: string): number {
   return ({ critical: 0, high: 1, medium: 2, low: 3, info: 4 } as Record<string, number>)[s] ?? 5;
 }
 
-function textBlock(title: string, body: string | undefined) {
+function proseBlock(
+  title: string,
+  body: string | undefined,
+  locale: Locale,
+  nameMap: Record<string, string>,
+  talentSpellIds: Record<string, number>,
+) {
   if (!body) return null;
   return (
     <Card>
       <h3 className="mb-2 text-sm font-semibold uppercase tracking-wide text-zinc-400">{title}</h3>
-      <p className="whitespace-pre-line text-sm text-zinc-200">{body}</p>
+      <ProseWithLinks
+        text={body}
+        locale={locale}
+        nameMap={nameMap}
+        talentSpellIds={talentSpellIds}
+      />
     </Card>
   );
 }