eve-mentor-mcp 0.1.0

package/dist/combat.js

@@ -0,0 +1,137 @@
+/**
+ * Combat coaching: ammo/damage-type advice and mechanical fit analysis.
+ * Damage tables follow EVE University's canonical NPC damage reference
+ * (https://wiki.eveuniversity.org/NPC_damage_types).
+ */
+import { esiFetch, getType, resolveNames } from "./esi.js";
+const AMMO_BY_DAMAGE = {
+    EM: {
+        projectile: "EMP S/M/L",
+        missile: "Mjolnir missiles",
+        drones: "Amarr drones (Acolyte/Infiltrator/Praetor)",
+        laser: "any crystal (lasers always deal EM+Thermal)",
+        hybrid: "not available — hybrids only deal Kinetic+Thermal",
+    },
+    Thermal: {
+        projectile: "Phased Plasma S/M/L",
+        missile: "Inferno missiles",
+        drones: "Gallente drones (Hobgoblin/Hammerhead/Ogre)",
+        laser: "any crystal (lasers always deal EM+Thermal)",
+        hybrid: "any charge (hybrids always deal Kinetic+Thermal)",
+    },
+    Kinetic: {
+        projectile: "Titanium Sabot S/M/L",
+        missile: "Scourge missiles",
+        drones: "Caldari drones (Hornet/Vespa/Wasp)",
+        laser: "not available — lasers only deal EM+Thermal",
+        hybrid: "any charge (hybrids always deal Kinetic+Thermal)",
+    },
+    Explosive: {
+        projectile: "Fusion S/M/L",
+        missile: "Nova missiles",
+        drones: "Minmatar drones (Warrior/Valkyrie/Berserker)",
+        laser: "not available — lasers only deal EM+Thermal",
+        hybrid: "not available — hybrids only deal Kinetic+Thermal",
+    },
+};
+function advice(target, shootDamageTypes, incomingDamageTypes) {
+    const primary = shootDamageTypes[0];
+    return {
+        target,
+        shootDamageTypes,
+        incomingDamageTypes,
+        tankAgainst: incomingDamageTypes.join(" + "),
+        ammoExamples: AMMO_BY_DAMAGE[primary] ?? {},
+    };
+}
+const DAMAGE_ADVICE = {
+    guristas: advice("Guristas", ["Kinetic", "Thermal"], ["Kinetic", "Thermal"]),
+    serpentis: advice("Serpentis", ["Thermal", "Kinetic"], ["Thermal", "Kinetic"]),
+    "angel cartel": advice("Angel Cartel", ["Explosive", "Kinetic"], ["Explosive", "Kinetic"]),
+    "blood raiders": advice("Blood Raiders", ["EM", "Thermal"], ["EM", "Thermal"]),
+    sansha: advice("Sansha's Nation", ["EM", "Thermal"], ["EM", "Thermal"]),
+    "rogue drones": advice("Rogue Drones", ["EM", "Thermal"], ["Explosive", "Kinetic"]),
+    triglavian: advice("Triglavian Collective", ["Explosive", "Thermal"], ["Explosive", "Thermal"]),
+    "shield-tanked player": advice("Shield-tanked player ship", ["EM", "Thermal"], ["anything — match your tank to their guns"]),
+    "armor-tanked player": advice("Armor-tanked player ship", ["Explosive", "Kinetic"], ["anything — match your tank to their guns"]),
+};
+/** Damage-type advice for a target faction or tank type. */
+export function adviseAmmo(target) {
+    const normalized = target.toLowerCase();
+    const match = Object.keys(DAMAGE_ADVICE).find((key) => normalized.includes(key) || key.includes(normalized));
+    if (!match) {
+        return {
+            error: `No damage data for "${target}".`,
+            knownTargets: Object.values(DAMAGE_ADVICE).map((entry) => entry.target),
+        };
+    }
+    return DAMAGE_ADVICE[match];
+}
+// ---------- Fit analysis ----------
+const groupNameCache = new Map();
+async function getGroupName(groupId) {
+    const cached = groupNameCache.get(groupId);
+    if (cached)
+        return cached;
+    const { data } = await esiFetch(`/universe/groups/${groupId}/`);
+    groupNameCache.set(groupId, data.name);
+    return data.name;
+}
+const TURRET_GROUPS = ["Projectile Weapon", "Hybrid Weapon", "Energy Weapon"];
+const DAMAGE_MOD_TO_WEAPON = {
+    Gyrostabilizer: "Projectile Weapon",
+    "Magnetic Field Stabilizer": "Hybrid Weapon",
+    "Heat Sink": "Energy Weapon",
+    "Ballistic Control system": "Missile Launcher",
+};
+async function classifyModules(moduleNames) {
+    const unique = [...new Set(moduleNames)];
+    const resolved = await resolveNames(unique);
+    const types = resolved.inventory_types ?? [];
+    return Promise.all(types.map(async (entry) => {
+        const type = await getType(entry.id);
+        return { name: entry.name, group: await getGroupName(type.group_id) };
+    }));
+}
+function findRedFlags(modules) {
+    const flags = [];
+    const groups = modules.map((m) => m.group);
+    const turretClasses = TURRET_GROUPS.filter((turret) => groups.includes(turret));
+    const hasMissiles = groups.some((g) => g.includes("Missile Launcher"));
+    const weaponSystemCount = turretClasses.length + (hasMissiles ? 1 : 0);
+    if (weaponSystemCount > 1) {
+        flags.push(`MIXED WEAPON SYSTEMS (${[...turretClasses, ...(hasMissiles ? ["Missiles"] : [])].join(", ")}): ` +
+            "ships bonus exactly one weapon system; the others waste slots, fitting room, and ammo logistics. Pick the hull's bonused system.");
+    }
+    const hasShieldTank = groups.some((g) => g.includes("Shield"));
+    const hasArmorTank = groups.some((g) => g.includes("Armor") || g.includes("Hull"));
+    if (hasShieldTank && hasArmorTank) {
+        flags.push("MIXED TANK (shield and armor modules together): pick one. Splitting tank halves your effective HP and wastes slots that should hold damage or utility.");
+    }
+    const hasPropulsion = groups.some((g) => g.includes("Propulsion"));
+    if (!hasPropulsion) {
+        flags.push("NO PROPULSION MODULE (afterburner/microwarpdrive): speed controls range, and range controls every fight. Almost every fit wants one.");
+    }
+    for (const [damageMod, weaponGroup] of Object.entries(DAMAGE_MOD_TO_WEAPON)) {
+        const hasDamageMod = modules.some((m) => m.group === damageMod);
+        const hasMatchingWeapon = groups.some((g) => g.includes(weaponGroup));
+        if (hasDamageMod && !hasMatchingWeapon) {
+            flags.push(`${damageMod.toUpperCase()} FITTED WITHOUT ${weaponGroup.toUpperCase()}S: this damage module boosts a weapon type the fit doesn't carry — it does nothing.`);
+        }
+    }
+    return flags;
+}
+/**
+ * Mechanical fit check: classify modules by group and detect classic
+ * newbie mistakes. Interpretation/coaching is the AI client's job.
+ */
+export async function analyzeFit(moduleNames) {
+    const classified = await classifyModules(moduleNames);
+    const resolvedNames = new Set(classified.map((m) => m.name.toLowerCase()));
+    const unresolvedNames = [...new Set(moduleNames)].filter((name) => !resolvedNames.has(name.toLowerCase()));
+    return {
+        modules: classified,
+        redFlags: findRedFlags(classified),
+        unresolvedNames,
+    };
+}

package/dist/esi.js

@@ -0,0 +1,169 @@
+/**
+ * Thin client for EVE's public ESI API.
+ * Docs: https://esi.evetech.net/ui/
+ */
+const ESI_BASE = "https://esi.evetech.net/latest";
+const USER_AGENT = "eve-mentor-mcp/0.1.0 (https://github.com/henryjrobinson/eve-mentor-mcp)";
+export const JITA_REGION_ID = 10000002; // The Forge
+export const JITA_44_STATION_ID = 60003760; // Jita IV - Moon 4 - Caldari Navy Assembly Plant
+export class EsiError extends Error {
+    status;
+    path;
+    constructor(status, path, message) {
+        super(`ESI ${status} on ${path}: ${message}`);
+        this.status = status;
+        this.path = path;
+        this.name = "EsiError";
+    }
+}
+// ESI gives every client an error budget (default 100 per minute); blowing it
+// gets you temporarily banned. Pause when the budget runs low.
+const ERROR_BUDGET_FLOOR = 20;
+let errorBudgetPauseUntil = 0;
+// Unauthenticated GET responses carry an Expires header; honoring it keeps us
+// from re-downloading heavy endpoints (system kills/jumps, market orders).
+const responseCache = new Map();
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function esiFetch(path, options = {}) {
+    const isCacheable = (options.method ?? "GET") === "GET" && !options.token;
+    if (isCacheable) {
+        const cached = responseCache.get(path);
+        if (cached && cached.expiresAt > Date.now()) {
+            return { data: cached.data, pages: cached.pages };
+        }
+    }
+    if (errorBudgetPauseUntil > Date.now()) {
+        await sleep(errorBudgetPauseUntil - Date.now());
+    }
+    const response = await fetch(`${ESI_BASE}${path}`, {
+        method: options.method ?? "GET",
+        headers: {
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+            ...(options.body ? { "Content-Type": "application/json" } : {}),
+            ...(options.token ? { Authorization: `Bearer ${options.token}` } : {}),
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    const budgetRemaining = Number(response.headers.get("x-esi-error-limit-remain") ?? "100");
+    if (budgetRemaining < ERROR_BUDGET_FLOOR) {
+        const resetSeconds = Number(response.headers.get("x-esi-error-limit-reset") ?? "10");
+        errorBudgetPauseUntil = Date.now() + resetSeconds * 1000;
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        throw new EsiError(response.status, path, text.slice(0, 300));
+    }
+    const pages = Number(response.headers.get("x-pages") ?? "1");
+    const data = (await response.json());
+    if (isCacheable) {
+        const expiresHeader = response.headers.get("expires");
+        const expiresAt = expiresHeader ? new Date(expiresHeader).getTime() : 0;
+        if (expiresAt > Date.now()) {
+            responseCache.set(path, { data, pages, expiresAt });
+        }
+    }
+    return { data, pages };
+}
+/** Resolve exact names (items, systems, characters...) to IDs. */
+export async function resolveNames(names) {
+    const { data } = await esiFetch("/universe/ids/", {
+        method: "POST",
+        body: names,
+    });
+    return data;
+}
+const idNameCache = new Map();
+/** Resolve IDs of mixed categories back to names (cached). */
+export async function namesForIds(ids) {
+    const unique = [...new Set(ids)].filter((id) => id > 0);
+    const missing = unique.filter((id) => !idNameCache.has(id));
+    // ESI accepts max 1000 ids per call
+    for (let i = 0; i < missing.length; i += 1000) {
+        const batch = missing.slice(i, i + 1000);
+        try {
+            const { data } = await esiFetch("/universe/names/", { method: "POST", body: batch });
+            for (const entry of data)
+                idNameCache.set(entry.id, entry.name);
+        }
+        catch {
+            // Some IDs (e.g. deleted characters) are unresolvable; leave them unnamed.
+        }
+    }
+    const result = new Map();
+    for (const id of unique) {
+        result.set(id, idNameCache.get(id) ?? `unknown-${id}`);
+    }
+    return result;
+}
+const typeCache = new Map();
+export async function getType(typeId) {
+    const cached = typeCache.get(typeId);
+    if (cached)
+        return cached;
+    const { data } = await esiFetch(`/universe/types/${typeId}/`);
+    typeCache.set(typeId, data);
+    return data;
+}
+export async function getSystem(systemId) {
+    const { data } = await esiFetch(`/universe/systems/${systemId}/`);
+    return data;
+}
+/** Kills and jumps across all systems in the last hour. */
+export async function getSystemActivity(systemId) {
+    const [kills, jumps] = await Promise.all([
+        esiFetch("/universe/system_kills/"),
+        esiFetch("/universe/system_jumps/"),
+    ]);
+    const killEntry = kills.data.find((k) => k.system_id === systemId);
+    const jumpEntry = jumps.data.find((j) => j.system_id === systemId);
+    return {
+        shipKillsLastHour: killEntry?.ship_kills ?? 0,
+        podKillsLastHour: killEntry?.pod_kills ?? 0,
+        npcKillsLastHour: killEntry?.npc_kills ?? 0,
+        jumpsLastHour: jumpEntry?.ship_jumps ?? 0,
+    };
+}
+/** Best buy/sell prices for a type in The Forge, split out for Jita 4-4. */
+export async function getJitaPrices(typeId) {
+    const first = await esiFetch(`/markets/${JITA_REGION_ID}/orders/?type_id=${typeId}&order_type=all&page=1`);
+    let orders = first.data;
+    if (first.pages > 1) {
+        const restPages = Array.from({ length: first.pages - 1 }, (_, i) => i + 2);
+        const rest = await Promise.all(restPages.map((page) => esiFetch(`/markets/${JITA_REGION_ID}/orders/?type_id=${typeId}&order_type=all&page=${page}`)));
+        orders = orders.concat(...rest.map((r) => r.data));
+    }
+    const atJita = orders.filter((o) => o.location_id === JITA_44_STATION_ID);
+    const sells = atJita.filter((o) => !o.is_buy_order);
+    const buys = atJita.filter((o) => o.is_buy_order);
+    return {
+        bestSell: sells.length ? Math.min(...sells.map((o) => o.price)) : null,
+        bestBuy: buys.length ? Math.max(...buys.map((o) => o.price)) : null,
+        sellVolume: sells.reduce((sum, o) => sum + o.volume_remain, 0),
+        buyVolume: buys.reduce((sum, o) => sum + o.volume_remain, 0),
+    };
+}
+export async function getKillmail(killmailId, hash) {
+    const { data } = await esiFetch(`/killmails/${killmailId}/${hash}/`);
+    return data;
+}
+/** Map a killmail item flag to a human-readable fitting slot. */
+export function slotForFlag(flag) {
+    if (flag >= 11 && flag <= 18)
+        return "low slot";
+    if (flag >= 19 && flag <= 26)
+        return "mid slot";
+    if (flag >= 27 && flag <= 34)
+        return "high slot";
+    if (flag >= 92 && flag <= 94)
+        return "rig";
+    if (flag >= 125 && flag <= 128)
+        return "subsystem";
+    if (flag === 87)
+        return "drone bay";
+    if (flag === 5)
+        return "cargo";
+    return "other";
+}

package/dist/index.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * eve-mentor-mcp — MCP server that turns Claude into an EVE Online mentor.
+ * Public tools work immediately; character tools need EVE SSO login.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { authStatus, login } from "./auth.js";
+import { getAssetsSummary, getCharacterSheet, getSkillQueue, getTopSkills } from "./character.js";
+import { getJitaPrices, getSystem, getSystemActivity, getType, resolveNames, } from "./esi.js";
+import { getRecentLosses } from "./zkill.js";
+import { flightPlan } from "./skills.js";
+import { CAREER_PATHS } from "./careers.js";
+import { adviseAmmo, analyzeFit } from "./combat.js";
+import { defineJargon } from "./jargon.js";
+import { getPayGuide } from "./payguide.js";
+const server = new McpServer({ name: "eve-mentor", version: "0.3.0" }, {
+    instructions: "You are mentoring an EVE Online player. EVE's data changes with every patch: do NOT " +
+        "estimate prices, skill requirements, fits, or danger from training knowledge — only values " +
+        "returned by these tools are authoritative. If a tool can answer it, call the tool. " +
+        "Your job is to turn the returned data into clear, honest coaching for someone still learning the game.",
+});
+function asResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function asError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+// ---------- Public tools ----------
+server.tool("lookup_item", "Look up any EVE item, ship, or module by exact name. Returns its description and Jita market prices.", { name: z.string().describe('Exact in-game name, e.g. "Rifter" or "Damage Control II"') }, async ({ name }) => {
+    try {
+        const ids = await resolveNames([name]);
+        const type = ids.inventory_types?.[0];
+        if (!type) {
+            return asError(`No item named "${name}" found. Names must be exact.`);
+        }
+        const [info, prices] = await Promise.all([getType(type.id), getJitaPrices(type.id)]);
+        return asResult({
+            name: info.name,
+            typeId: info.type_id,
+            description: info.description.replace(/<[^>]+>/g, ""),
+            jitaMarket: prices,
+        });
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("system_intel", "Danger report for a solar system: security status, ship/pod kills and traffic in the last hour.", { system_name: z.string().describe('Exact system name, e.g. "Jita" or "Tama"') }, async ({ system_name }) => {
+    try {
+        const ids = await resolveNames([system_name]);
+        const match = ids.systems?.[0];
+        if (!match) {
+            return asError(`No system named "${system_name}" found. Names must be exact.`);
+        }
+        const [system, activity] = await Promise.all([
+            getSystem(match.id),
+            getSystemActivity(match.id),
+        ]);
+        const security = Number(system.security_status.toFixed(1));
+        return asResult({
+            system: system.name,
+            securityStatus: security,
+            securityClass: security >= 0.5 ? "high-sec" : security > 0 ? "low-sec" : "null-sec",
+            lastHour: activity,
+        });
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("recent_losses", "A character's recent ship losses from zKillboard with full fit detail — the raw material for explaining why they died. Works for any character name, no login needed.", {
+    character_name: z.string().describe("Exact character name"),
+    limit: z.number().int().min(1).max(10).default(3).describe("How many losses (1-10)"),
+}, async ({ character_name, limit }) => {
+    try {
+        const losses = await getRecentLosses(character_name, limit);
+        if (losses.length === 0) {
+            return asResult({ message: `${character_name} has no recorded losses on zKillboard.` });
+        }
+        return asResult(losses);
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("can_i_fly", "What does it take to fly/use a ship or module? Returns the full recursive skill prerequisite tree, an ordered training plan, total skillpoints, and estimated training time. If a character is logged in, the plan is diffed against their actual trained skills.", { item_name: z.string().describe('Exact ship or module name, e.g. "Vexor" or "Damage Control II"') }, async ({ item_name }) => {
+    try {
+        const ids = await resolveNames([item_name]);
+        const type = ids.inventory_types?.[0];
+        if (!type) {
+            return asError(`No item named "${item_name}" found. Names must be exact.`);
+        }
+        return asResult(await flightPlan(type.id, type.name));
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("ammo_advisor", "Which damage type to shoot (and tank) against a target: NPC pirate factions (Guristas, Serpentis, Angels, Blood Raiders, Sansha, Rogue Drones, Triglavians) or shield/armor-tanked players. Includes concrete ammo names per weapon system.", { target: z.string().describe('Faction or tank type, e.g. "Guristas" or "armor-tanked player"') }, async ({ target }) => {
+    try {
+        return asResult(adviseAmmo(target));
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("analyze_fit", "Mechanical fit check: classifies each module by type and detects classic mistakes (mixed weapon systems, mixed shield+armor tank, no propulsion, damage mods without matching weapons). Feed it module names from a loss report or a pasted fit, then explain the findings to the player.", {
+    module_names: z
+        .array(z.string())
+        .min(1)
+        .describe("Module names exactly as they appear in the fit/killmail"),
+}, async ({ module_names }) => {
+    try {
+        return asResult(await analyzeFit(module_names));
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("career_test", "Data for the EVE career 'sorting hat'. Returns all recognized career paths with traits (social/risk/income/activity, who it appeals to, first ship, first steps). To use: interview the player about what they enjoy (solo vs group, risk appetite, building vs fighting vs exploring, active vs idle, how much structure they want), THEN call this and match their answers to 2-3 paths. Recommend concrete first steps, not just labels.", {}, async () => {
+    try {
+        return asResult(CAREER_PATHS);
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("jargon", "EVE slang glossary. Pass a term to define it, or no term to list everything known. Use whenever the player hits a word like 'krab', 'tidi', 'doctrine', or 'asset safety'.", { term: z.string().optional().describe("The slang term to define; omit to list all terms") }, async ({ term }) => {
+    try {
+        return asResult(defineJargon(term));
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("cheapest_way_to_play", "EVE's pay-vs-play economy explained with live numbers: Alpha (free) vs Omega (subscribed), how PLEX lets you buy game time with ISK instead of money, today's actual Jita price for an Omega month, and an honest grind-hours-vs-cash recommendation.", {}, async () => {
+    try {
+        return asResult(await getPayGuide());
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("sitrep", "Session-start situation report in one call: login state, character overview (skillpoints/wallet/location/ship), what's training, and the most recent loss. Call this at the start of a mentoring session to orient.", {}, async () => {
+    const report = {};
+    const auth = await authStatus();
+    report.auth = auth;
+    if (auth.loggedIn && auth.characterName) {
+        const [sheet, queue, losses] = await Promise.allSettled([
+            getCharacterSheet(),
+            getSkillQueue(),
+            getRecentLosses(auth.characterName, 1),
+        ]);
+        report.character = sheet.status === "fulfilled" ? sheet.value : `unavailable: ${sheet.reason}`;
+        report.skillQueue = queue.status === "fulfilled" ? queue.value.slice(0, 5) : `unavailable: ${queue.reason}`;
+        report.lastLoss = losses.status === "fulfilled" ? (losses.value[0] ?? "no recorded losses") : `unavailable: ${losses.reason}`;
+    }
+    else {
+        report.note = "Not logged in — use eve_login for a personalized sitrep, or ask for the player's character name to pull public loss history.";
+    }
+    return asResult(report);
+});
+// ---------- Auth + character tools ----------
+server.tool("eve_login", "Start the EVE Online login flow. Opens a browser for SSO; the user must complete it within 3 minutes.", {}, async () => {
+    try {
+        const result = await login();
+        return asResult({ loggedIn: true, ...result });
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("eve_auth_status", "Check whether an EVE character is currently logged in.", {}, async () => {
+    try {
+        return asResult(await authStatus());
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("character_sheet", "The logged-in character's overview: total skillpoints, wallet, current location, and ship.", {}, async () => {
+    try {
+        return asResult(await getCharacterSheet());
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("skill_queue", "The logged-in character's current skill training queue.", {}, async () => {
+    try {
+        return asResult(await getSkillQueue());
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("my_assets", "Everything the logged-in character owns, grouped by location. Flags asset-safety wraps and structures the character can no longer dock at — use this to find stuff stranded from years ago.", {}, async () => {
+    try {
+        return asResult(await getAssetsSummary());
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+server.tool("top_skills", "The logged-in character's highest-trained skills — useful for judging what they can fly well.", { limit: z.number().int().min(1).max(50).default(15).describe("How many skills (1-50)") }, async ({ limit }) => {
+    try {
+        return asResult(await getTopSkills(limit));
+    }
+    catch (error) {
+        return asError(error);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/jargon.js

@@ -0,0 +1,70 @@
+/**
+ * EVE slang glossary — the jargon wall is a researched top-10 new-player
+ * pain point and no other tool addresses it. Definitions follow EVE
+ * University wiki usage.
+ */
+export const GLOSSARY = {
+    ratting: "Killing NPC pirates ('rats') in belts or anomalies for bounty ISK.",
+    krab: "Someone farming PvE income (ratting/mining) instead of fighting; 'krabbing' is doing that. Mildly derogatory, mostly affectionate.",
+    dscan: "Directional scanner (Alt+D): shows ships/structures within 14.3 AU. Spamming it is how you see hunters coming.",
+    gank: "Killing a much weaker or unprepared target, often suicide-attacking in high-sec where CONCORD will kill you back.",
+    gatecamp: "Players parked at a stargate killing whatever jumps through. Check zKillboard before flying low-sec pipes.",
+    pod: "Your escape capsule after your ship dies. Getting 'podded' means losing that too — you wake up in a clone.",
+    "pod express": "Getting podded on purpose (or accepting it) as free instant travel back to your home station.",
+    plex: "Two meanings: PLEX the item (30 days of game time, buyable/sellable for ISK) and 'plexing' (capturing faction-warfare complexes).",
+    doctrine: "A fleet's standardized ship fitting. 'Doctrine ships' are what your alliance tells you to fly so logi can keep you alive.",
+    fc: "Fleet Commander — calls targets and movement. 'FC, what do?' is the eternal question.",
+    srp: "Ship Replacement Program — your alliance reimburses ships lost on sanctioned fleets. Makes fleet PvP nearly free.",
+    hisec: "High security space (0.5–1.0): CONCORD punishes attackers. Not safe, just policed.",
+    lowsec: "Low security (0.1–0.4): no CONCORD response, gate guns only. Faction warfare and pirate country.",
+    nullsec: "0.0 space: no law at all, player alliances own it. Big fleets, big riches, bubbles.",
+    jspace: "Wormhole space (J-numbered systems): no local chat, no stargates, mapped only by scanning.",
+    local: "The chat channel listing everyone in your system — null-sec's primary intel tool. Watch it like a smoke detector.",
+    blob: "An overwhelmingly larger fleet. 'Getting blobbed' = losing to numbers, not skill.",
+    kite: "Fighting at range while staying faster than the enemy can close. Opposite of brawling.",
+    brawl: "Close-range, high-damage slugging match. Webs and scrams decide it.",
+    tackle: "Holding an enemy ship in place with warp disruption so it can't escape. The newbie fleet job that gets you on every killmail.",
+    point: "Warp Disruptor (1 warp-strength block, longer range). 'Point!' in fleet chat means 'I have them tackled.'",
+    scram: "Warp Scrambler (2 strength, short range, also shuts off microwarpdrives).",
+    web: "Stasis Webifier — slows the target so your guns track and your scram range holds.",
+    neut: "Energy Neutralizer — drains the target's capacitor so their guns/reps/prop die.",
+    dps: "Damage per second. Also shorthand for the damage-dealing ships in a fleet (vs tackle/logi).",
+    tank: "Your defenses. Buffer tank = raw HP, active tank = repairing yourself. Pick shield OR armor, never both.",
+    logi: "Logistics ships — fleet healers that remote-repair friendlies. Always blamed, never thanked.",
+    alpha: "Two meanings: an Alpha clone (free-to-play account) or alpha strike (one massive volley before the target can react).",
+    omega: "A subscribed account: all skills available, double training speed.",
+    cyno: "Cynosural field — a beacon capital ships jump to. Lighting one in the wrong place is how supercarriers die.",
+    capital: "The big ships: carriers, dreadnoughts, supercarriers, titans. Null-sec endgame, terrible newbie purchases.",
+    bait: "A deliberately vulnerable-looking ship with friends one jump away. If it looks too easy, it is.",
+    awox: "Attacking your own corpmates from inside the corp. Why corps are paranoid about recruits.",
+    tidi: "Time dilation — the server slowing time (down to 10%) so thousand-player battles can compute.",
+    jita: "The main trade hub (Jita 4-4 station). Everything is for sale; undocking there is the most dangerous trip in high-sec.",
+    "asset safety": "When you lose access to a player structure, your stuff moves to a recoverable holding system (delivered to an NPC station for a fee). Your items are never deleted.",
+    concord: "The high-sec police. They don't prevent crime — they punish it after your ship is already dead.",
+    "sec status": "Your personal security rating. Goes down for attacking players in hisec/lowsec; below -5 you're freely attackable everywhere.",
+    standings: "NPC factions' opinion of you. Gates which mission agents will talk to you.",
+    lp: "Loyalty Points — mission/FW currency spent in corp stores for faction gear. Often worth more than the ISK reward.",
+    abyssals: "Abyssal Deadspace — timed instanced PvE dungeons entered with filaments. Die inside or run out of time and you lose everything.",
+    filament: "Consumable that teleports you into abyssal space or across the universe (Pochven/null filaments).",
+    "jump clone": "A second body you can jump into across the map (with cooldown) — lets you keep an expensive-implant clone safe at home.",
+    align: "Pointing your ship at a warp target so warp engages instantly. 'Align out' = be ready to flee.",
+    bubble: "Warp disruption field in null-sec that stops everyone in it from warping — no targeting needed. Why null travel kills newbies.",
+    bm: "Bookmark — a saved location in space. Safe spots, undock points, and tactical perches are all bookmarks.",
+};
+export function defineJargon(term) {
+    if (!term) {
+        return { knownTerms: Object.keys(GLOSSARY).sort() };
+    }
+    const normalized = term.toLowerCase().trim();
+    const exact = GLOSSARY[normalized];
+    if (exact)
+        return { term: normalized, definition: exact };
+    const partial = Object.entries(GLOSSARY).filter(([key]) => key.includes(normalized) || normalized.includes(key));
+    if (partial.length > 0) {
+        return Object.fromEntries(partial);
+    }
+    return {
+        error: `"${term}" isn't in the glossary yet.`,
+        knownTerms: Object.keys(GLOSSARY).sort(),
+    };
+}

package/dist/payguide.js

@@ -0,0 +1,58 @@
+/**
+ * The pay-vs-play guide: EVE's Alpha/Omega/PLEX economy explained with live
+ * numbers. PLEX is an in-game item tradeable for ISK, so subscription time
+ * can be bought with play instead of money — the math changes monthly.
+ */
+import { esiFetch } from "./esi.js";
+const PLEX_TYPE_ID = 44992;
+const PLEX_PER_OMEGA_MONTH = 500;
+const STATIC_GUIDE = {
+    alpha: {
+        cost: "Free, forever.",
+        whatYouGet: "All four empires' Tech 1 ships up through battleships, a limited skill set, and normal access to the same single universe as everyone else.",
+        limits: "Skill training stops at the Alpha set (~5M skillpoints of free training; more via injectors), trains at half speed, no Tech 2 ships, one logged-in character at a time.",
+        honestTake: "Alpha is a real game, not a demo — exploration, faction warfare, and trading all work. It is the right way to find out if EVE sticks before paying anything.",
+    },
+    omega: {
+        cost: "A subscription — paid with real money OR with PLEX bought from other players with ISK.",
+        whatYouGet: "Every ship and skill in the game, double training speed, multiple training queues per account.",
+    },
+    plexExplained: "PLEX is game time as a tradeable item: someone with more money than time buys PLEX with cash and sells it on the market for ISK; someone with more time than money earns ISK and buys that PLEX for game time. Both players get what they want, and CCP gets paid either way. It also means every ship in EVE has a real-world price shadow — which is why big battles make gaming news with dollar figures.",
+    cheapestPaths: [
+        "1. Start Alpha. Pay nothing until the game has actually hooked you.",
+        "2. If it hooks you, pay cash for the first Omega month or two — your early hours are worth more spent learning than grinding for PLEX.",
+        "3. Once your income is real (see the live math below for the bar), decide each month: grind the PLEX price in ISK, or pay cash and spend those hours having fun.",
+        "4. Watch for starter-pack sales — discounted Omega+skillpoint bundles for new/returning accounts are common and usually the best cash value.",
+    ],
+    trap: "Buying PLEX with cash to sell for ISK to buy ships ('whaling') is legal but is how people spend hundreds of dollars learning to lose ships. Earn the cheap ships first.",
+};
+/** Live cost of an Omega month in ISK, with honest grind-hours context. */
+export async function getPayGuide() {
+    let liveMath;
+    try {
+        // PLEX trades on a special global market, not regional order books, so use
+        // ESI's universe-wide average price.
+        const { data } = await esiFetch("/markets/prices/");
+        const plexPrice = data.find((entry) => entry.type_id === PLEX_TYPE_ID)?.average_price;
+        if (plexPrice) {
+            const omegaMonthIsk = Math.round(plexPrice * PLEX_PER_OMEGA_MONTH);
+            liveMath = {
+                plexAveragePrice: Math.round(plexPrice),
+                omegaMonthInIsk: omegaMonthIsk,
+                omegaMonthReadable: `${(omegaMonthIsk / 1e9).toFixed(2)} billion ISK for ${PLEX_PER_OMEGA_MONTH} PLEX`,
+                grindContext: `At rough new-player income estimates (10-40M ISK/hour from exploration or L3 missions), ` +
+                    `that's ~${Math.round(omegaMonthIsk / 40e6)}-${Math.round(omegaMonthIsk / 10e6)} hours of grinding per month. ` +
+                    "If that number is bigger than your monthly play time, pay cash and spend your hours on fun.",
+            };
+        }
+        else {
+            liveMath = { error: "PLEX price missing from ESI market prices." };
+        }
+    }
+    catch (error) {
+        liveMath = {
+            error: `Live PLEX price unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { ...STATIC_GUIDE, liveMath };
+}