@@ -186,22 +186,12 @@ pub async fn search(
 }
 
 /// The most-downloaded addons for a flavor, for a search box nobody has typed
-/// in yet.
+/// in yet: ranked by popularity alone, from WoWInterface's catalogue already
+/// on disk, so Browse has rows before the first keystroke.
 ///
-/// A different question from [`search`], not a search with no words: there is
-/// nothing to match, so nothing to rank by match, and the whole order is
-/// popularity. WoWInterface answers it out of the catalogue already on disk,
-/// so the Browse tab has rows before the first keystroke and at no cost.
-///
-/// Tukui is deliberately absent. It publishes no download counts at all, so
-/// its two addons would either sit at the bottom of a popularity list as
-/// zeroes or have to be given a rank they did not earn, and ElvUI belongs
-/// nowhere near the bottom. It is one search away.
-///
-/// A provider that cannot answer is dropped rather than reported, unlike in
-/// [`search`]: this list is the default view of a tab, not the answer to a
-/// question somebody asked, and a standing warning over a page nobody asked
-/// to load is noise. A search says so properly.
+/// Tukui is left out: it publishes no download counts, and ElvUI does not
+/// belong at the bottom. A provider that cannot answer is dropped silently,
+/// unlike in [`search`]: this is a tab's default view, not a question asked.
 pub async fn popular(
     http: &Http,
     catalog: Option<&Catalog>,
 
@@ -95,25 +95,18 @@ pub fn of_file(path: &Path) -> Option<u32> {
 
 /// The fingerprint of an addon folder, as CurseForge computes it.
 ///
-/// Reverse-engineered against 34 folders from two unrelated addons whose
-/// published fingerprints the catalog states, and it reproduces all 34. The
-/// parts that are not guessable from the outside, in the order they bite:
+/// Reverse-engineered against 34 folders from two addons; reproduces all 34.
+/// The parts that cannot be guessed:
 ///
-/// 1. **Not every file counts.** The set is the folder's `.toc` files, the
-///    paths those tocs *load*, and the files the client loads implicitly.
-///    Only unconditionally, though: a line carrying a `[...]` clause,
-///    `BossPrototype.lua [ExcludeLoadGameType vanilla]`: is out, and so is
-///    a file nothing references. BigWigs has 338 files on disk and a
-///    fingerprint over 19.
-/// 2. **Each file is hashed, then the hashes are hashed.** Per file it is
-///    [`of_bytes`]; the folder is those numbers written out as decimal,
-///    concatenated, and hashed again.
-/// 3. **Sorted by value, not by name.** Ascending numeric order of the file
-///    hashes themselves, which is why no filename ordering ever matched.
+/// 1. **Not every file counts.** Only the `.toc` files, the paths they load
+///    unconditionally (a line with a `[...]` clause is out) and the files the
+///    client loads implicitly. BigWigs: 338 files on disk, 19 hashed.
+/// 2. **Hash of hashes.** Each file is [`of_bytes`]; the folder hashes those
+///    numbers written as decimal and concatenated.
+/// 3. **Sorted by value**, not by name.
 ///
-/// `None` when the folder declares nothing, no toc, or a toc that loads
-/// nothing that exists. An addon with no fingerprint cannot be adopted,
-/// which is the honest outcome rather than hashing an arbitrary subset.
+/// `None` when the folder loads nothing that exists; such an addon cannot be
+/// adopted, rather than hashing an arbitrary subset.
 pub fn of_folder(dir: &Path) -> Option<u32> {
     let mut hashes: Vec<u32> = declared(dir)
         .iter()
 
@@ -320,17 +320,11 @@ pub struct Extracted {
 
 /// Extract an addon package into `addons_dir`.
 ///
-/// Replaces the folders it contains: an update must not leave a removed file
-/// from the previous version behind, since a stale `.lua` can break an addon
-/// far more confusingly than a missing one. `retire` names more folders to
-/// take away in the same step, the ones a repair replaces that this build no
-/// longer ships.
-///
-/// Nothing installed is touched until the whole package is on disk. It is
-/// written to a staging folder beside `AddOns`, on the same filesystem, and
-/// only then swapped in folder by folder with renames. A full disk or an I/O
-/// error while writing leaves the old addon exactly as it was, and a failed
-/// rename puts back every folder already swapped.
+/// Replaces whole folders, since a stale `.lua` left from the last version
+/// breaks an addon more confusingly than a missing one; `retire` names extra
+/// folders to remove in the same step. The package is written to a staging
+/// folder beside `AddOns` first, then swapped in by rename, so a full disk
+/// leaves the old addon intact and a failed rename puts back what it swapped.
 pub fn extract(package: &[u8], addons_dir: &Path, retire: &[String]) -> Result<Extracted, InstallError> {
     extract_within(package, addons_dir, retire, MAX_UNCOMPRESSED)
 }
 
@@ -610,17 +610,11 @@ pub struct Adopted {
 
 /// Recognise hand-installed addons and take them into the ledger.
 ///
-/// An addon Lightforge did not install has no provider and no id, so it can
-/// be listed and nothing else, no update, no channel, no removal. Hashing
-/// each unmanaged folder the way CurseForge does (see
-/// [`crate::addons::fingerprint`]) and asking the catalog whose it is turns
-/// it into an ordinary managed addon.
-///
-/// Conservative in both directions. A folder already owned by a record is
-/// left alone, so this cannot take an addon away from the entry that
-/// installed it. And a match is only written for folders that are *actually
-/// present*: the catalog answers with the whole package, and recording a
-/// folder that is not there would have removal promise to delete it.
+/// An unmanaged folder can only be listed; fingerprinting it the way
+/// CurseForge does (see [`crate::addons::fingerprint`]) and asking the catalog
+/// makes it an ordinary managed addon. A folder another record owns is left
+/// alone, and only folders actually present are recorded, so a later removal
+/// never promises to delete one that is not there.
 pub async fn adopt(
     http: &Http,
     catalog: Option<&Catalog>,
 
@@ -28,22 +28,13 @@ use sha2::{Digest, Sha256};
 use crate::net::{ETagCache, Http, NetError};
 use crate::product::{Branch, Catalog, CatalogEntry, ProductCode};
 
-/// Manifest schema this build understands.
+/// Manifest schema this build understands. A newer one is refused: the last
+/// good cached art beats half-understood theming.
 ///
-/// A manifest declaring a newer schema is refused rather than parsed
-/// optimistically: the cached art from the last good fetch is a better answer
-/// than half-understood theming.
-///
-/// **2** made `logo` and `background` optional, so a product can be themed
-/// with nothing but its square mark. Battle.net hand-offs, Diablo,
-/// Hearthstone, StarCraft, are never drawn with a logo or a background by
-/// this launcher, but they do want a mark in the product bar and the browse
-/// list, and under schema 1 that was unreachable without inventing a wordmark
-/// and a background for each of them.
-///
-/// The bump is deliberate and not merely additive: a schema-1 client reading
-/// a manifest whose entries omit `logo` fails to parse the *whole* document,
-/// so it must be told to keep its cached copy instead.
+/// **2** made `logo` and `background` optional, so a Battle.net hand-off can
+/// be themed with just its square mark. Not merely additive: a schema-1 client
+/// fails to parse the whole document when an entry omits `logo`, so it must
+/// be told to keep its cache.
 pub const SCHEMA_VERSION: u32 = 2;
 
 /// File name of the manifest within its base URL or fixture directory.
@@ -176,18 +167,11 @@ impl Manifest {
 
     /// The theme of this product's *line*: Classic's for Classic PTR.
     ///
-    /// The step between a product's own entry and `default`. A PTR is the
-    /// same game as the branch it tracks, so when the manifest does not name
-    /// it, the game it belongs to is a far better answer than whatever
-    /// `default` happens to be: without this, Era PTR and Classic PTR both
-    /// wore retail's logo and backdrop, because retail is what `default`
-    /// points at.
-    ///
-    /// For the head itself, or a head the manifest does not name, the first
-    /// other branch that has a theme. Forever's head is `wowf`, and a
-    /// manifest naming `wowf` would make 1.0.0-beta.3 and older install it
-    /// into a literal `wowf/` (they do not know the code), so its art stays
-    /// on `wow_classic_beta` and the live product borrows it from there.
+    /// Between a product's own entry and `default`; without it both PTRs wore
+    /// retail's art. For a head the manifest does not name, the first other
+    /// branch with a theme: Forever's head is `wowf`, and naming `wowf` in the
+    /// manifest would make 1.0.0-beta.3 and older install into a literal
+    /// `wowf/`, so its art stays on `wow_classic_beta`.
     fn head_theme(&self, code: &ProductCode) -> Option<&Theme> {
         let line = code.line();
         let head = line.head();
@@ -355,22 +339,12 @@ impl Store {
 
     /// Delete cached art that `keep` does not name.
     ///
-    /// Published art is content-addressed upstream, the filename carries the
-    /// first bytes of its sha256, so every image that changes arrives under
-    /// a *new* URL, and the cache file for the old one is never written to
-    /// again. Without this, a few megabytes are stranded on disk per art
-    /// revision, forever.
-    ///
-    /// Deliberately narrow about what it will remove: only direct children,
-    /// only names that look like something [`Store::cache_name`] produced,
-    /// and never the manifest. A cache directory is still someone's disk, and
-    /// a prune that mis-fires there is far worse than the leak it fixes.
-    ///
-    /// **Each kept file keeps its `.etag` sidecar too.** Missing that was a
-    /// real bug: every pass deleted every validator, so the next revalidation
-    /// had nothing to send, re-downloaded art it already had, and the UI
-    /// swapped pictures that had not changed, which looks like the page
-    /// flickering a second after each product switch.
+    /// Art is content-addressed upstream, so every revision arrives under a new
+    /// URL and the old cache file would be stranded forever. Narrow on
+    /// purpose: direct children only, names [`Store::cache_name`] could have
+    /// produced, never the manifest. **Each kept file keeps its `.etag`
+    /// sidecar**: deleting those once made every revalidation re-download and
+    /// swap unchanged pictures, a flicker after each product switch.
     pub fn prune(&self, keep: &[String]) -> usize {
         let mut wanted: std::collections::HashSet<String> =
             std::collections::HashSet::with_capacity(keep.len() * 2);
@@ -544,18 +518,10 @@ impl Pipeline {
 
     /// Resolve branding from what is already on disk, touching no network.
     ///
-    /// A warm cache holds the exact bytes the UI is about to draw, so making
-    /// it wait on a revalidation round trip before painting buys nothing but
-    /// a few hundred milliseconds of unthemed dashboard. This hands back the
-    /// last good art at once; [`Pipeline::resolve_with`] follows behind and
-    /// swaps in whatever actually changed.
-    ///
-    /// `None` whenever the cache cannot fully answer, a missing manifest, an
-    /// unthemed product, an image not fetched yet, or one that no longer
-    /// matches its checksum. Partial branding is not a thing the UI can draw,
-    /// so a half-warm cache simply waits for the network like a cold one.
-    ///
-    /// Blocking file IO: call it off the thread that is drawing.
+    /// The warm cache paints at once; [`Pipeline::resolve_with`] follows and
+    /// swaps in whatever changed. `None` unless the cache can answer fully
+    /// (manifest, theme, every image present and matching its checksum):
+    /// partial branding cannot be drawn. Blocking IO: call it off the UI thread.
     pub fn cached(&self, code: &ProductCode) -> Option<Branding> {
         let manifest = self.cached_manifest()?;
         let theme = manifest.theme(code)?;
 
@@ -538,24 +538,17 @@ pub const AUTOSTART_MINIMIZED_KEY: &str = "User.Client.AutoStartMinimized";
 
 /// Start the client minimized, or normally.
 ///
-/// Two keys, because the client decides this for itself and neither one is
-/// enough alone. It logs the whole decision on every start:
+/// The client logs its decision on every start:
 ///
 /// ```text
 /// [Frontend] {Main} Attempting to show main window. isMinimizedOnStartup=false
 /// shouldMainWindowShowMinimizedAtAutoStartup=false varAutoStarted=false …
-/// needToMinimize=false …
 /// ```
 ///
-/// `isMinimizedOnStartup` is the Qt window state below, what the client wrote
-/// out of its own window when it last exited. `shouldMainWindowShow…` is the
-/// preference above, and it is only consulted when `varAutoStarted` is set,
-/// which is what [`Launch::Autostart`] is for. Setting the preference without
-/// that flag changes nothing, which is why the window kept appearing.
-///
-/// Both have to be re-applied before each start, because the client writes the
-/// window state back from its live window every time it exits, the same reason
-/// the game's CVars are reconciled per launch rather than set once.
+/// `isMinimizedOnStartup` is the Qt window state below; the preference above
+/// is only read when `varAutoStarted` is set, which is what
+/// [`Launch::Autostart`] is for. Both are re-applied before each start because
+/// the client writes its window state back on every exit.
 pub fn window_state_tweaks(minimized: bool) -> Vec<Tweak> {
     vec![
         Tweak::new(
@@ -637,20 +630,15 @@ const READY_POLL: Duration = Duration::from_millis(250);
 
 /// Wait until the client says it is signed in.
 ///
-/// Watches the newest log in [`Layout::battle_net_logs`] that the client
-/// wrote *after* `since`, so a previous session's log cannot answer for this
-/// one. Reading a log file is the whole mechanism. Nothing is injected,
-/// nothing is scraped out of the client's memory, and the marker is a line
-/// the client prints for its own benefit:
+/// Reads the newest log in [`Layout::battle_net_logs`] written after `since`
+/// (so an old session cannot answer) for the client's own marker. Nothing is
+/// injected or read from its memory.
 ///
 /// ```text
-/// I [GSStateTracker] State changed to: Ready
-/// I [AccountManager] Account manager state has changed to: Ready
 /// I [BNLogin] Logged into Battle.net successfully. |bnet=…
 /// ```
 ///
-/// Measured on a cold start under Proton: about five and a half seconds from
-/// the process appearing to the sign-in line.
+/// About 5.5 s from process start on a cold Proton start.
 pub fn wait_until_ready(
     layout: &Layout,
     user: &str,
@@ -1016,19 +1004,10 @@ pub enum Launch {
     /// `repair` and `modify` in its binary against the descriptions "Start a
     /// package installation" and "Game registration/installation uid".
     InstallFlow { uid: String },
-    /// A `battlenet://` link, handed to the client the way the system would.
-    ///
-    /// The form Wine registered for the protocol at install time:
-    ///
-    /// ```text
-    /// [Software\Classes\battlenet\shell\open\command]
-    /// @="\"C:\Program Files (x86)\Battle.net\Battle.net.exe\" --uri=\"%1\""
-    /// ```
-    ///
-    /// This is how Blizzard's own web buttons drive the client, which makes
-    /// it the one documented way to say "show me this game", and unlike a
-    /// tile selection it is a command the client acts on rather than view
-    /// state its own startup can overwrite.
+    /// A `battlenet://` link, handed over the way Wine registered the protocol
+    /// (`Battle.net.exe --uri="%1"`). It is how Blizzard's own web buttons
+    /// drive the client, and a command the client acts on rather than view
+    /// state its startup can overwrite.
     Uri(String),
 }
 
@@ -1094,13 +1073,10 @@ pub fn game_uri(family: &str) -> String {
     format!("battlenet://{family}")
 }
 
-/// Battle.net's own identifier for a game, as used by `--exec="launch <uid>"`.
+/// Battle.net's id for a game's tile, as `--exec="launch <uid>"` wants it.
 ///
-/// **This is not the TACT product code.** The client works in *game family*
-/// ids, one per tile in its library, and the flavor within a tile comes from
-/// its version dropdown. Read out of the client's own log, where each selection
-/// is recorded (`Selecting game family by id: …` followed by
-/// `Active product set to: …`):
+/// **Not the TACT product code.** The client works in game families, one per
+/// tile, read out of its log (`Selecting game family by id: …`):
 ///
 /// ```text
 /// WoW  -> WoWX12_retail
@@ -1109,18 +1085,10 @@ pub fn game_uri(family: &str) -> String {
 /// W3   -> W3_retail
 /// ```
 ///
-/// Passing a TACT code here is not a no-op. It is worse. The client fails to
-/// resolve it and **falls back to the first family it knows, which is
-/// Warcraft III**, so the user lands on a game they may not even own. That was
-/// a real bug: `launch wow_classic_era` put Gabriel on the W3 page every time.
-/// The family for a product, preferring what is compiled in and falling back
-/// to the client's own catalogue.
-///
-/// That order, not the other way round: the WoW families were read out of a
-/// real log and carry decisions the catalogue cannot express, a PTR and a
-/// beta live in the retail tile's version list, and Forever is a tile of its
-/// own. Everything else comes from [`crate::families`], which knows every
-/// title Blizzard publishes rather than the two that were observed.
+/// A TACT code here makes the client fall back to its first family, Warcraft
+/// III, which is where `launch wow_classic_era` used to land. The compiled-in
+/// WoW families come first (a PTR and a beta live in the retail tile, Forever
+/// has its own); everything else comes from [`crate::families`].
 pub fn resolve_game_uid(code: &ProductCode, families: &crate::families::Families) -> Option<String> {
     game_uid(code).or_else(|| families.family_of(code.as_str()).map(str::to_owned))
 }
 
@@ -108,17 +108,11 @@ pub struct Config {
     pub battle_net_minimized: bool,
     /// How Battle.net and every game it launches are started.
     ///
-    /// **Shared, not per-game, and that is the mechanism rather than a
-    /// simplification.** Lightforge only ever sets the environment of a
-    /// Battle.net client it starts *cold*; a client that is already up takes
-    /// the launch over its own IPC queue, where there is no new process to
-    /// give an environment to. Two games started from one client session
-    /// therefore cannot have different environments, so offering a per-game
-    /// control would be a lie; see `SPEC.md`, "Per-product pinning".
-    ///
-    /// Only the host and runtime half of [`crate::tweaks::Tweaks`] is read
-    /// here. A hand-off game has no `Config.wtf`, so
-    /// [`crate::tweaks::Tweaks::cvars`] is never called on this value.
+    /// Shared, not per game: Lightforge only sets the environment of a client
+    /// it starts cold, and a running client takes launches over IPC, so two
+    /// games from one session cannot differ (`SPEC.md`, "Per-product
+    /// pinning"). A hand-off game has no `Config.wtf`, so only the host and
+    /// runtime half of [`crate::tweaks::Tweaks`] is read.
     #[serde(default)]
     pub battle_net_tweaks: crate::tweaks::Tweaks,
     /// Which of Blizzard's regions products are downloaded from.