# VoidScout — CurseForge Submission

Copy each field below into the matching CurseForge form input when creating/editing the project.

## Basic info

**Project name**: VoidScout

**Slug**: `voidscout`

**Summary** (the one-line summary field):
> Behavior-based applicant & group scoring for Premade Groups — vet who actually kicks, dispels, avoids mechanics, and finishes keys, not just their rating.

**Categories** (pick the closest CurseForge offers):
- Group Finder / Guild
- Combat
- Data Export

**Game version compatibility**: 12.0.7

**License**: All Rights Reserved (or MIT if you prefer to match the others — your call)

**Project URL**: https://www.curseforge.com/wow/addons/voidscout (after creation)

---

## Description

(Paste into the description editor. CurseForge accepts Markdown.)

---

**Utility-aware applicant and group scoring for Looking-For-Group premade content.** Where RaiderIO
tells you a player's *score*, VoidScout tells you their *behavior* — interrupts, dispels, mechanic
avoidance, staying for the whole key, pulling their weight. It's the signal that actually decides
whether a pug times the key or wipes on the first boss.

### Why use it
M+ rating and ilvl tell you what a player *can* do on paper. They don't tell you whether they kick,
dispel, sidestep avoidable damage, or bail the moment a key looks dicey. VoidScout surfaces that
behavioral track record — and a forward-looking estimate of how someone will perform in *your* group
for *this* content — **before** you invite.

### The 8-axis Utility model
Every logged player is graded on eight plain-English axes: **Damage, Interrupts, Dispels,
Avoidance, Activity, Survival, Teamwork, Commitment** (per-pug stay rate — do they finish keys or
bail). These roll up into a **Utility Score**.

### Probability Score — forward-looking, with coaching
A 0–99 estimate of how a player will perform in *your* group for the *listed content* — and it tells
you **why**, in plain language: *"Avoidance 52 — eating mechanics," "Interrupts 70 — missing
priority kicks," "Damage 69 — push CDs/trinkets."* Coaching, not just a number — useful for vetting
applicants **and** improving your own play.

### TimedPossibility
A 0–99 group score for whether a specific roster can realistically time a given keystone level —
based on the composition's collective execution, not just raw rating.

### Fair scoring — Role & duty declaration
You're only graded on what you're responsible for. The **Role Picker** auto-sets your role from your
spec and lets you declare duties (Kicks, Soaks, Dispels, Add Duty, Rescues, plus boss-specific
duties that appear in known fights). A per-boss mechanic database then grades you only on the
mechanics you *could and should* have handled — a DPS isn't dinged for a dispel that wasn't theirs.

### Where you see it
- **Premade Groups panel** — a RaiderIO-style profile docks beside the finder: Utility Score, the
  eight axes, RaiderIO rating, raid progress matrix, timed keys, and the Probability Score.
- **Applicant-row badges** — leaders get a Probability badge on every applicant, to scan the whole
  queue at a glance.
- **Enriched tooltips** — mouse over anyone for their CE/AOTC/KSM tier, gear, raid progress, M+
  score, top keys, Utility Score, and the Behavior line (interrupt percentile + kick count).
- **Minimap button** + shared VoidHub icon cluster.

### How it works (and why it's safe)
Scoring data comes from Blizzard's official **`C_DamageMeter`** engine — *not* the combat log —
deliberately, to stay clear of the 12.0 secret-value taint that breaks SecureActionButton addons.
With your consent, per-fight summaries upload to **api.voidscout.io** for server-side scoring, and a
baked-in data bundle brings computed scores back in-game so lookups are instant and offline.

### Data & privacy
A first-run dialog spells out exactly what's collected before anything leaves your client.
**Local-only mode** keeps everything on your machine; **uploads** can be toggled anytime; and
**`/vs optout`** requests deletion of your server-side data. It scores behavior — not chat or
personal data — and honors a server-side opt-out list.

### The companion uploader (optional)
WoW addons can't make web requests, so contributing your data uses a small **separate companion app** —
**voidscout-uploader** (open-source/MIT, a single ~7 MB binary, no install dependencies). It watches
your SavedVariables and uploads scored fights to api.voidscout.io. VoidScout works fully without it
(bundle-backed scores + tooltips); the uploader just lets your own data feed the shared pool. Opt-in,
uploads only combat-performance data. **Get it for your OS at https://voidscout.io/install** (or the
GitHub Releases: github.com/bughatti/voidscout-uploader).

### Recommended companion
**RaiderIO** — VoidScout blends its M+/raid rating in alongside the behavioral scores.

### Slash commands
- `/vs` — settings / consent options
- `/vs optout` · `/vs optin` — switch upload mode (and request deletion)
- `/vs autosetup` — re-run the one-time damage-meter cvar setup

> Note: behavioral scores exist for players who've been *logged* through VoidScout, so coverage
> grows with the user base. For everyone else, RaiderIO rating + raid/M+ data carry the vetting.

---

## Screenshots (upload + captions)

Recommended gallery order — lead with the coaching panel, it's the most compelling:

1. **`Screenshot ...172127.png`** — *Full score panel: 8 behavioral axes, raid-progress matrix, and the Probability Score with plain-language coaching.*
2. **`Screenshot ...172039.png`** — *Enriched tooltip: achievement tier, gear, raid progress, M+ score, and the Behavior line (kick %) at a glance.*
3. **`Screenshot ...172249.png`** — *Vetting an applicant in Premade Groups — their Probability Score for the listed key.*
4. **`Screenshot ...172516.png`** — *Role Picker: declare your role + duties so you're only scored on what you're responsible for.*
5. *(optional)* The panel docked to the Premade Groups finder with the applicant list — the "where you use it" context shot.
6. *(optional)* The first-run consent dialog — showcases the upfront privacy handling.

(Files are in `C:\Users\liquidai\Pictures\Screenshots\`.)

---

## Pre-release checklist
- [x] Interface bumped to 120007
- [x] Login chat spam removed
- [x] README + this submission doc
- [ ] Create the CurseForge project to get the project ID
- [ ] Add `"VoidScout": <projectID>` to `tools/cmd/upload-curseforge/main.go`
- [ ] Add the public-repo mapping to `sync-to-public.sh` (if you want a public GitHub mirror)
- [ ] Confirm the shipped `VoidScoutBundle.lua` contains only VoidScout-computed + Blizzard-API data
