diff --git a/src/conversion.cpp b/src/conversion.cpp
index a5cfd4f3..a8852bb2 100644
--- a/src/conversion.cpp
+++ b/src/conversion.cpp
@@ -18,16 +18,12 @@ extern "C" {
 #include <htslib/tbx.h>
 }
 
-// Run a bcftools function in a forked child process. bcftools main_* use global optind
-// and other process-wide state; forking gives each call its own address space for safe
-// parallelism.
+// Run a bcftools function in a forked child. bcftools main_* use global optind and other
+// process-wide state; forking gives each call its own address space for safe parallelism.
 static int run_bcftools_in_fork(int (*func)(int, char**), int argc, char** argv, bool silenceStderr = true) {
-    // Serialize the forks. fork() from a TBB worker (batch mode, --threads > 1)
-    // clones only the calling thread; if another worker holds a stdio/htslib lock
-    // at fork time, the child can deadlock acquiring it (the owner doesn't exist in
-    // the child). glibc/macOS already make malloc fork-safe via atfork handlers, so
-    // the remaining exposure is two bcftools children running concurrently. This
-    // lock allows at most one bcftools fork in flight at a time.
+    // Serialize forks: fork() from a TBB worker clones only the calling thread, so a lock
+    // another worker holds (stdio/htslib) can deadlock the child. This mutex bounds it to one
+    // bcftools fork in flight (malloc is already fork-safe via atfork).
     static std::mutex forkMutex;
     std::lock_guard<std::mutex> forkLock(forkMutex);
 
@@ -313,11 +309,8 @@ static bam1_t* build_bam_from_result(const std::string& qname_full,
         qname.resize(qname.size() - 2);
     }
 
-    // R2 of a pair is reverse-complemented upstream (readFastqPaired) before alignment,
-    // so the aligner's rev bit for it is inverted relative to the original fragment.
-    // Report the original read's true strand in the FLAG and TLEN; the stored SEQ/CIGAR
-    // stay in the aligned (forward-reference) orientation, which is what BAM expects for
-    // either strand.
+    // R2 was reverse-complemented upstream, so the aligner's rev bit is inverted vs the original
+    // fragment. Report true strand in FLAG/TLEN; SEQ/CIGAR stay forward-reference, as BAM expects.
     const uint8_t effective_rev = (is_paired && !is_read1) ? static_cast<uint8_t>(!aln->rev) : aln->rev;
     uint16_t flag = compute_sam_flags(is_paired, is_read1, effective_rev, mate_rev, proper_frag, mate_unmapped);
 
diff --git a/src/gap_map_utils.hpp b/src/gap_map_utils.hpp
index 8eb2515c..b4fc5201 100644
--- a/src/gap_map_utils.hpp
+++ b/src/gap_map_utils.hpp
@@ -277,10 +277,8 @@ void invertGapMap(std::map<T, T>& gapMap,
         // start inside of a range
         auto curIt = leftIt;
         if (static_cast<int64_t>(end) <= static_cast<int64_t>(curIt->second)) {
-            // [start, end] lies entirely within one gap run; reversing an all-gap span
-            // is a no-op. Without this clamp, the walk below appended a run to the gap's
-            // end plus a negative-length run, corrupting the gap map (e.g. inverting
-            // [10,20] inside {0:30} dropped [21,30]).
+            // [start,end] within one gap run: reversing an all-gap span is a no-op; without this
+            // clamp the walk emits a negative-length run (inverting [10,20] inside {0:30} dropped [21,30]).
             blockRuns.emplace_back(true,
                                    std::make_pair(static_cast<int64_t>(start), static_cast<int64_t>(end)));
         } else {
diff --git a/src/genotyping.cpp b/src/genotyping.cpp
index c8da322f..3698af06 100644
--- a/src/genotyping.cpp
+++ b/src/genotyping.cpp
@@ -245,10 +245,8 @@ std::string genotyping::applyMutationSpectrum(const std::string& line,
 
     gls[0] += scaled_submat[ref_nuc_idx][ref_nuc_idx];
     for (size_t i = 1; i < gls.size(); i++) {
-        // scaled_submat is the 4x4 A/C/G/T substitution-spectrum prior, so apply
-        // it only to base ALTs. A non-base ALT (e.g. '*' spanning deletion) has
-        // index > 3 and would over-read the row, so leave its likelihood
-        // unmodified. Matches how indels use the unmodified bcftools posterior.
+        // scaled_submat is the 4x4 A/C/G/T substitution prior; apply only to base ALTs. A
+        // non-base ALT (e.g. '*') has index >3 and would over-read the row, so leave it as-is.
         int alt_idx = getIndexFromNucleotide(alts[i - 1]);
         if (alt_idx <= 3) {
             gls[i] = gls[i] + scaled_submat[ref_nuc_idx][alt_idx];
@@ -264,9 +262,9 @@ std::string genotyping::applyMutationSpectrum(const std::string& line,
 
     if (min_gl_index == 0) return "";
 
-    // Consensus gate: only emit an ALT that is the majority allele and has at least
-    // minDepth high-quality reads. Guards against bcftools (and, at low coverage, the
-    // spectrum prior) emitting sub-majority or shallow ALTs as false positives.
+    // Consensus gate: emit an ALT only if it's the majority allele with >= minDepth
+    // high-quality reads. Guards against bcftools / the low-coverage spectrum prior
+    // emitting sub-majority or shallow false-positive ALTs.
     if (!passesConsensusGate(min_gl_index, ads, minDepth)) return "";
 
     gt = min_gl_index;
diff --git a/src/genotyping.hpp b/src/genotyping.hpp
index 842b19b7..09f0efda 100644
--- a/src/genotyping.hpp
+++ b/src/genotyping.hpp
@@ -34,11 +34,10 @@ void fillMutationMatricesFromFile(mutationMatrices& mutMat, std::ifstream& inf);
 std::string applyMutationSpectrum(const std::string& line, const std::vector<std::vector<double>>& scaled_submat,
                                   int minDepth, double minQual);
 
-// Field-standard consensus gate for haploid genotyping: the called allele (calledIdx
-// into AD; 0 = ref) must (a) be the majority — strictly more high-quality reads than
-// all other alleles combined — and (b) be supported by at least minDepth high-quality
-// reads. Below that, a position should be a no-call (ref/N), not a variant. Returns
-// true (no filtering) only when AD is missing/uninformative.
+// Consensus gate for haploid genotyping: the called allele (calledIdx into AD; 0 = ref)
+// must be the majority (strictly more high-quality reads than all others combined) and
+// have >= minDepth high-quality reads, else the position is a no-call. Returns true (no
+// filtering) only when AD is missing/uninformative.
 bool passesConsensusGate(int calledIdx, const std::vector<int>& ad, int minDepth);
 // Same gate applied to a raw VCF sample field ("GT:PL:AD").
 bool passesConsensusGate(const std::string& sampleField, int minDepth);
diff --git a/src/index_single_mode.cpp b/src/index_single_mode.cpp
index 6497ca9f..b55d6f89 100644
--- a/src/index_single_mode.cpp
+++ b/src/index_single_mode.cpp
@@ -345,9 +345,8 @@ std::vector<panmapUtils::NewSyncmerRange> index_single_mode::IndexBuilder::compu
                 localRangeCoordToGlobalScalarCoords.push_back(curCoordScalar);
                 localRangeCoordToBlockId.push_back(curCoord.primaryBlockId);
             } else if (refOnSyncmers.contains(curCoordScalar)) {
-                // Only delete seeds inside the genome extent. Flank regions (before
-                // firstNonGapScalar or after lastNonGapScalar) are missing data, not true
-                // gaps; their seeds stay inherited from the parent.
+                // Only delete seeds inside the genome extent; flank regions are missing
+                // data, not true gaps, so their seeds stay inherited from the parent.
                 if (std::cmp_greater_equal(curCoordScalar, firstNonGapScalar) &&
                     std::cmp_less_equal(curCoordScalar, lastNonGapScalar)) {
                     blockOnSyncmers[curCoord.primaryBlockId].erase(curCoordScalar);
@@ -368,9 +367,8 @@ std::vector<panmapUtils::NewSyncmerRange> index_single_mode::IndexBuilder::compu
                     recomputeBlock = false;
                     recomputeInProgress = false;
                     if (curCoordGapMapIt != gapMap.end()) {
-                        // At begin() there is no previous run, so the lower bound
-                        // (prev->second < curCoordScalar) is vacuously satisfied;
-                        // guard the std::prev to avoid dereferencing before begin().
+                        // At begin() there is no previous run (lower bound vacuously
+                        // satisfied); guard std::prev to avoid dereferencing before begin().
                         while (curCoordGapMapIt != gapMap.end() &&
                                !((curCoordGapMapIt == gapMap.begin() ||
                                   std::cmp_less(std::prev(curCoordGapMapIt)->second, curCoordScalar)) &&
@@ -1386,11 +1384,8 @@ void index_single_mode::IndexBuilder::computeSubstitutionSpectrum() {
             uint32_t blockId = blockMut.primaryBlockId;
             bool oldExists = blockSequences.blockExists[blockId];
             blockUndoRecord.emplace_back(blockId, oldExists);
-            // Match the canonical block-existence rule (panmap_utils.cpp): an
-            // insertion makes the block exist (even when also inverted); a
-            // non-inversion deletion removes it; an inversion of an existing
-            // block leaves existence unchanged. blockMutInfo=false marks both
-            // deletions and inversions, so it can't be assigned directly.
+            // Canonical block-existence rule (panmap_utils.cpp): insertion sets exists, non-inversion
+            // deletion clears it, inversion leaves it unchanged; blockMutInfo=false marks del+inv both.
             if (blockMut.blockMutInfo) {
                 blockSequences.blockExists[blockId] = true;
             } else if (!blockMut.inversion) {
@@ -2367,9 +2362,8 @@ void index_single_mode::IndexBuilder::buildIndexParallel(int numThreads) {
 
             totalClonesCreated_.fetch_add(1, std::memory_order_relaxed);
 
-            // Walk from root to the range's first node, then DFS through the range.
-            // Nodes 0..startDfs-1 are ancestors or earlier siblings that must be walked.
-            // Compute nodeChanges only for nodes in [startDfs, endDfs).
+            // Walk from root to the range's first node, then DFS through the range. Compute
+            // nodeChanges only for nodes in [startDfs, endDfs); earlier nodes are just walked.
 
             std::function<void(panmanUtils::Node*, uint64_t)> processDfsRange = [&](panmanUtils::Node* node,
                                                                                     uint64_t dfsIdx) {
diff --git a/src/index_single_mode.hpp b/src/index_single_mode.hpp
index 9b686410..6c6d2c89 100644
--- a/src/index_single_mode.hpp
+++ b/src/index_single_mode.hpp
@@ -21,19 +21,16 @@
 
 namespace index_single_mode {
 
-// A small uncompressed header prepended to the .idx so cache-validation can read the
-// seeding params without decompressing the (up to GB-scale) payload -- previously the
-// validation step fully decompressed the index just to read six fields, then the
-// placement step decompressed it a second time.
+// Uncompressed header prepended to the .idx so cache-validation can read the seeding
+// params without decompressing the (up to GB-scale) payload.
 constexpr uint32_t kIndexMagic = 0x31494D50u;  // "PMI1" little-endian
 constexpr uint32_t kIndexHeaderVersion = 1;
 constexpr size_t kIndexHeaderSize = 32;
 struct IndexParamsHeader {
     int32_t k = 0, s = 0, t = 0, l = 0;
     bool hpc = false, open = false;
-    // When set, the payload after the header is raw (unframed) capnp bytes rather than
-    // ZSTD frames, so load can mmap it and hand the bytes straight to capnp (zero-copy,
-    // no decompression pass). Bigger on disk, faster to load.
+    // When set, payload is raw (unframed) capnp bytes, not ZSTD frames, so load can mmap
+    // and hand them straight to capnp (zero-copy). Bigger on disk, faster to load.
     bool uncompressed = false;
 };
 std::array<uint8_t, kIndexHeaderSize> encodeIndexHeader(const IndexParamsHeader& p);
@@ -69,10 +66,8 @@ struct BuildState {
     std::map<uint64_t, uint64_t> gapMap;
     std::unordered_set<uint64_t> invertedBlocks;
 
-    // first/last non-gap scalar positions. Seeds in flank regions (before
-    // firstNonGapScalar or after lastNonGapScalar) are missing data, not true gaps,
-    // so must not be deleted when they become gaps. Permissive by default; only
-    // restricted when extentGuard is on.
+    // first/last non-gap scalar positions. Seeds in flank regions are missing data, not
+    // true gaps, so must not be deleted when they become gaps; permissive unless extentGuard is on.
     uint64_t firstNonGapScalar = 0;
     uint64_t lastNonGapScalar = UINT64_MAX;
 
diff --git a/src/logging.hpp b/src/logging.hpp
index 5d679572..73929e05 100644
--- a/src/logging.hpp
+++ b/src/logging.hpp
@@ -106,7 +106,6 @@ inline const char* cross() {
 }
 }  // namespace box
 
-// Spinner frames (Braille pattern, 10 frames at ~80ms = ~12fps)
 inline const char* spinner_frame(int i) {
     static const char* frames[] = {"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"};
     static const char* plain_frames[] = {"|", "/", "-", "\\", "|", "/", "-", "\\", "|", "/"};
@@ -165,8 +164,6 @@ inline void debug(const std::string& msg) {
     std::cerr << style::dim() << msg << style::reset() << "\n";
 }
 
-// Buffered single-line dim stream for routine log lines. detail() visible unless
-// --quiet; trace() only under --verbose.
 class LineBuf {
    public:
     explicit LineBuf(bool enabled) : enabled_(enabled) {}
@@ -181,7 +178,7 @@ class LineBuf {
         return *this;
     }
 
-    // ostream manipulators (std::endl / std::flush) flush the line immediately.
+    // std::endl / std::flush flush the line immediately.
     LineBuf& operator<<(std::ostream& (*)(std::ostream&)) {
         emit();
         return *this;
@@ -211,18 +208,13 @@ inline LineBuf trace() {
     return LineBuf(config().verbose && !config().quiet);
 }
 
-// One-line tool+version banner.
 inline void banner(const std::string& version, const std::string& /*subtitle*/ = "") {
     if (config().quiet) return;
     std::cerr << style::bold() << "panmap" << style::reset() << style::dim() << " " << version << style::reset()
               << "\n\n";
 }
 
-// Stage line columns:
-//   "  ICN  LABEL.  SUBJECT.................  STAT.........    TIME"
-// Subject/stat are left-padded to a min width so columns align across stages;
-// time is right-padded so right edges line up. Input strings must be plain text
-// (no ANSI codes) or the width math breaks; apply styling via the helpers below.
+// Stage-line inputs must be plain text (no ANSI) or the column width math breaks.
 constexpr int kLabelWidth = 6;
 constexpr int kSubjectWidth = 22;
 constexpr int kStatWidth = 14;
@@ -242,8 +234,7 @@ inline std::string pad_left(const std::string& s, int w) {
     return std::string(w - s.size(), ' ') + s;
 }
 
-// Truncate to w columns, keeping the tail (informative end of a path) behind a
-// leading ellipsis. Assumes ASCII content.
+// Keeps the tail behind a leading ellipsis. Assumes ASCII content.
 inline std::string truncate_tail(const std::string& s, int w) {
     if (w <= 0) return "";
     if ((int)s.size() <= w) return s;
@@ -270,9 +261,6 @@ inline void write_status_line(const std::string& icon,
                               const std::string& stat,
                               int64_t ms) {
     if (config().quiet) return;
-    // Subject column flexes to terminal width so stat/time columns stay aligned
-    // across rows; long subjects (paths) are tail-truncated. Non-TTY (piped/log)
-    // keeps the full subject and the original min width.
     int subjectW;
     if (config().isTTY) {
         int iconW = config().plain ? static_cast<int>(icon.size()) : 1;
@@ -312,7 +300,6 @@ inline void done(const std::string& what, int64_t ms) {
               << style::reset() << "\n";
 }
 
-// Trailing blank line before the shell prompt.
 inline void summary(int64_t /*total_ms*/) {
     if (config().quiet) return;
     std::cerr << "\n";
@@ -335,7 +322,6 @@ inline void step(const std::string& msg) {
     std::cerr << style::dim() << "  " << msg << style::reset() << "\n";
 }
 
-// Indeterminate progress message (one line, overwritten in place).
 inline void progress(const std::string& msg) {
     if (config().quiet || !config().isTTY || config().plain) return;
     std::cerr << "\r\033[K" << style::dim() << "  " << msg << style::reset() << std::flush;
@@ -345,9 +331,6 @@ inline void progress_clear() {
     if (config().isTTY && !config().plain) std::cerr << "\r\033[K" << std::flush;
 }
 
-// Progress bar. In-place line:
-//     <spinner> <label>  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸    42%  · 1.2s
-// clear() leaves the line empty so the caller can emit a done() line.
 class ProgressBar {
    public:
     ProgressBar(std::string label, uint64_t total) : label_(std::move(label)), total_(total) {
@@ -399,11 +382,10 @@ class ProgressBar {
         std::string pct = fmt::format("{:>3}%", static_cast<int>(frac * 100));
         std::string ela = format_duration(elapsed);
 
-        // Layout: "  <spin> <label-padded> <bar>  <pct>  · <ela>"
         std::string label_padded = label_;
         if ((int)label_padded.size() < kLabelWidth) label_padded.append(kLabelWidth - label_padded.size(), ' ');
 
-        // Reserved visible chars (no ANSI): "  X " + label + " " + bar + "  " + "NNN%" + "  · " + ela
+        // Reserved visible (no ANSI) cols: "  X " + label + " " + bar + "  " + "NNN%" + "  · " + ela
         int reserved = 2 + 1 + 1 + (int)label_padded.size() + 1 + 2 + 4 + 4 + (int)ela.size();
         int width = term_width();
         int bar_w = width - reserved - 2;
@@ -457,10 +439,7 @@ inline bool check_interrupted(bool print_message = true) {
     return false;
 }
 
-// Async-signal-safe handler. Exits immediately on first Ctrl-C/SIGTERM rather than
-// polling a flag: long stages (8M-node index, EM rounds) never poll, so a polite
-// path looks stuck. Outputs are written all-at-once at stage end, so an interrupt
-// mid-stage leaves no partial artifact.
+// Async-signal-safe: _Exit immediately rather than poll a flag (long stages never poll).
 inline void handler(int signum) {
     (void)signum;
     static const char msg[] = "\ninterrupted\n";
diff --git a/src/main.cpp b/src/main.cpp
index 55331463..3d60b353 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -14,8 +14,7 @@
 #include <tbb/global_control.h>
 #include <tbb/parallel_for.h>
 #include <tbb/tbb.h>
-// Compatibility shim: oneTBB 2021+ uses tbb::filter_mode enum class.
-// TBB 2019 uses tbb::filter::serial_in_order nested enum.
+// oneTBB 2021+ uses tbb::filter_mode; older TBB uses the nested tbb::filter enum.
 #if defined(TBB_VERSION_MAJOR) && TBB_VERSION_MAJOR >= 2021
 #define TBB_FILTER_SERIAL_IN_ORDER tbb::filter_mode::serial_in_order
 #define TBB_FILTER_PARALLEL tbb::filter_mode::parallel
@@ -80,51 +79,49 @@ inline const char* bold() {
 }  // namespace color
 
 enum class PipelineStage {
-    Index,      // Build index only
-    Place,      // Placement only
-    Align,      // Placement + Alignment
-    Genotype,   // Placement + Alignment + Genotyping
-    Consensus,  // + Consensus FASTA generation
-    Full        // Full pipeline
+    Index,
+    Place,
+    Align,
+    Genotype,
+    Consensus,
+    Full
 };
 
 struct Config {
-    std::string panman;  // Guide pangenome (.panman)
-    std::string reads1;  // First read file (FASTQ/FASTA)
-    std::string reads2;  // Second read file for paired-end
+    std::string panman;
+    std::string reads1;
+    std::string reads2;
 
-    std::string output;    // Output prefix
-    std::string index;     // Pre-built index to load (--index)
-    std::string indexOut;  // Where to write the index when building (--index-out)
+    std::string output;
+    std::string index;
+    std::string indexOut;
 
     PipelineStage stopAfter = PipelineStage::Place;
     bool forceReindex = false;
 
-    bool metagenomic = false;  // Metagenomic mode (multi-sample)
-    int topN = 1;              // Report top N placements
-    bool dedupReads = false;   // Deduplicate reads before placement (for amplicon data)
+    bool metagenomic = false;
+    int topN = 1;
+    bool dedupReads = false;
 
     std::string aligner = "minimap2";
 
-    // Index parameters
-    int k = 19;                   // syncmer k
-    int s = 8;                    // syncmer s
-    int l = 3;                    // l-mer size
+    int k = 19;
+    int s = 8;
+    int l = 3;
     int t = 0;                    // syncmer offset
     bool openSyncmer = false;
-    int flankMaskBp = 250;        // Hard mask first/last N bp at genome ends
-    double seedMaskFraction = 0;  // Fraction of most-frequent seeds to mask (0 disables masking)
-    int minSeedQuality = 0;       // Min avg Phred quality for seed region (0=disabled)
-    int trimStart = 0;            // Trim N bases from start of each read (primer removal)
-    int trimEnd = 0;              // Trim N bases from end of each read (primer removal)
-    int minReadSupport = -1;      // Min reads for a seed to be counted; -1 = auto (2 if est. coverage > 3x, else 1)
-    bool hpc = false;             // Homopolymer-compressed seeds
-    bool extentGuard = false;     // Guard seed deletions at genome extent boundaries
+    int flankMaskBp = 250;
+    double seedMaskFraction = 0;  // 0 disables masking
+    int minSeedQuality = 0;
+    int trimStart = 0;
+    int trimEnd = 0;
+    int minReadSupport = -1;      // -1 = auto (2 if est. coverage > 3x, else 1)
+    bool hpc = false;
+    bool extentGuard = false;
 
     int threads = 1;
     int zstdLevel = 7;
 
-    // Metagenomic options
     bool indexPacked = false;
     bool readPacked = false;
     bool indexUncompressed = false;
@@ -153,7 +150,6 @@ struct Config {
     bool pseudochain = false;
     size_t batchSize = 1000000;
 
-    // Utility modes
     std::string dumpNodeId;
     uint32_t dumpRandomNodeIDs = 0;
     std::vector<std::string> dumpSequences;
@@ -165,47 +161,39 @@ struct Config {
     bool writeOCRanks = false;
     int seed = 42;
 
-    std::string batchFile;  // Path to batch file listing samples (one per line: reads1 [reads2])
+    std::string batchFile;
 
-    std::string dumpAllScores;  // Dump all node scores to this file
+    std::string dumpAllScores;
 
-    bool quiet = false;    // Minimal output (errors only)
-    bool verbose = false;  // Extra debug output
-    bool plain = false;    // Plain text output (no colors/unicode)
+    bool quiet = false;
+    bool verbose = false;
+    bool plain = false;
 
-    bool forceLeaf = false;  // Restrict placement to leaf nodes only
+    bool forceLeaf = false;
 
-    // Consensus options
-    bool impute = false;              // Impute N's from parent sequence (ignore _->N mutations)
-    bool noMutationSpectrum = false;  // Skip mutation spectrum filtering in VCF
-    bool baq = false;                 // Enable BAQ (Base Alignment Quality) in mpileup
-    int minDepth = 1;                 // Min high-quality read depth to call a consensus variant
-    double minQual = 30.0;            // Min bcftools variant QUAL to call a consensus variant
+    bool impute = false;              // ignore _->N mutations
+    bool noMutationSpectrum = false;
+    bool baq = false;
+    int minDepth = 1;
+    double minQual = 30.0;
 
-    // Pre-computed substitution spectrum from index (4x4 phred-scaled matrix)
-    // Empty if index has no spectrum or --no-mutation-spectrum is set
-    std::vector<std::vector<double>> substMatrixPhred;
+    std::vector<std::vector<double>> substMatrixPhred;  // 4x4 phred-scaled; empty if unavailable
 
-    // Alignment-based refinement options
-    bool refine = false;           // Enable alignment-based refinement
-    double refineTopPct = 0.01;    // Top X% of nodes to refine (default 1%)
-    int refineMaxTopN = 150;       // Max nodes to align against
-    int refineNeighborRadius = 2;  // Expand to neighbors within N branches
-    int refineMaxNeighborN = 150;  // Max additional nodes from neighbor expansion
+    bool refine = false;
+    double refineTopPct = 0.01;
+    int refineMaxTopN = 150;
+    int refineNeighborRadius = 2;
+    int refineMaxNeighborN = 150;
 };
 
-// Cap'n Proto reader with ZSTD decompression
 class IndexReader : public ::capnp::MessageReader {
    public:
     std::vector<uint8_t> data;
-    // Held for the uncompressed path; the mmap must outlive `reader` (declared after it,
-    // so it is destroyed first), which points directly into the mapped bytes.
+    // mmap must outlive `reader` (declared after it, so destroyed first), which points into it.
     boost::iostreams::mapped_file_source mmapFile;
     std::unique_ptr<::capnp::FlatArrayMessageReader> reader;
 
     explicit IndexReader(const std::string& path, int numThreads = 0) : ::capnp::MessageReader(makeOptions()) {
-        // New-format indexes carry a small uncompressed param header before the payload;
-        // skip it. Old-format indexes (no header) decompress from offset 0.
         index_single_mode::IndexParamsHeader ph;
         const bool hasHeader = index_single_mode::readIndexHeader(path, ph);
         const size_t dataOffset = hasHeader ? index_single_mode::kIndexHeaderSize : 0;
@@ -213,9 +201,7 @@ class IndexReader : public ::capnp::MessageReader {
         const capnp::word* words = nullptr;
         size_t numWords = 0;
         if (hasHeader && ph.uncompressed) {
-            // Uncompressed index: mmap and hand the bytes straight to capnp (zero-copy,
-            // no decompression pass). dataOffset (32) is 8-aligned within the page-aligned
-            // mapping, so the word cast is properly aligned.
+            // dataOffset (32) is 8-aligned within the page-aligned mapping, so the word cast is aligned.
             mmapFile.open(path);
             if (!mmapFile.is_open()) {
                 throw std::runtime_error("Failed to mmap index: " + path);
@@ -296,13 +282,11 @@ class FdReader {
     }
 };
 
-// Load 4x4 substitution matrix from index and convert to phred scale.
-// Returns empty matrix if index has no spectrum data.
+// Returns empty if the index has no spectrum data.
 std::vector<std::vector<double>> loadSubstMatrixFromIndex(LiteIndex::Reader& idx) {
     auto matReader = idx.getSubstitutionMatrix();
     if (matReader.size() != 16) return {};
 
-    // Check if matrix is populated (non-identity)
     bool allZeroOffDiag = true;
     for (int i = 0; i < 4 && allZeroOffDiag; i++)
         for (int j = 0; j < 4; j++)
@@ -312,7 +296,7 @@ std::vector<std::vector<double>> loadSubstMatrixFromIndex(LiteIndex::Reader& idx
             }
     if (allZeroOffDiag) return {};
 
-    // Convert probability matrix to phred: -10 * log10(p)
+    // phred = -10 * log10(p)
     std::vector<std::vector<double>> phred(4, std::vector<double>(4, 0.0));
     for (int i = 0; i < 4; i++)
         for (int j = 0; j < 4; j++) {
@@ -378,11 +362,8 @@ bool buildMgsrIndex(const Config& cfg) {
     return true;
 }
 
-// A cached single-sample index is reusable only if it was built for the same
-// request: matching seeding parameters (k/s/t/l/hpc/open-syncmer) and not older
-// than the panman. Placement reads the seeding params back out of the index, so a
-// stale cache would silently override the user's CLI parameters (or an edited
-// panman). On any mismatch — or an unreadable index — rebuild.
+// Reusable only if seeding params match and the index is newer than the panman: placement
+// reads params back from the index, so a stale cache would silently override CLI params.
 static bool cachedIndexUsable(const Config& cfg) {
     if (fs::exists(cfg.panman)) {
         boost::system::error_code ecIdx, ecPan;
@@ -393,8 +374,6 @@ static bool cachedIndexUsable(const Config& cfg) {
             return false;
         }
     }
-    // Read the seeding params from the small uncompressed header instead of decompressing
-    // the whole (up to GB-scale) payload just to compare six fields.
     index_single_mode::IndexParamsHeader ph;
     if (!index_single_mode::readIndexHeader(cfg.index, ph)) {
         logging::warn("Cached index {} has no readable param header (old format/corrupt); rebuilding.",
@@ -892,9 +871,7 @@ struct BatchEntry {
     std::string prefix;
 };
 
-// Parse a batch file: one sample per line, "reads1 [reads2] [output_prefix]"
-// (whitespace- or tab-separated). The output prefix is optional and auto-derived
-// from reads1 when omitted.
+// One sample per line: "reads1 [reads2] [output_prefix]". Prefix defaults from reads1.
 bool readBatchFiles(const std::string& batchPath, std::vector<BatchEntry>& entries) {
     std::ifstream batchIn(batchPath);
     if (!batchIn.is_open()) {
@@ -1219,9 +1196,7 @@ bool runMetagenomic(const Config& cfg) {
     std::unique_ptr<FdReader> fdReader;
     ::capnp::MessageReader* baseReader = nullptr;
 
-    // Pick the reader by sniffing the format rather than attempting the ZSTD
-    // reader first: MGSR indexes are plain (uncompressed) capnp, so a try-first
-    // approach logged a spurious "Not a valid ZSTD frame" on every run.
+    // Sniff for a ZSTD magic; MGSR indexes are plain capnp, so try-first would log a spurious error.
     bool indexIsZstd = false;
     {
         std::ifstream probe(cfg.index, std::ios::binary);
@@ -1299,8 +1274,7 @@ int runAlignment(const Config& cfg,
 int runGenotyping(const Config& cfg);
 int runConsensus(const Config& cfg);
 
-// refineEnabled is computed per-caller (it can be disabled after the full tree loads),
-// so it's passed in explicitly rather than read from cfg.
+// refineEnabled is passed in, not read from cfg: it can be disabled once the full tree loads.
 static placement::TraversalParams makeTraversalParams(const Config& cfg, bool refineEnabled) {
     placement::TraversalParams p;
     p.seedMaskFraction = cfg.seedMaskFraction;
@@ -1319,7 +1293,6 @@ static placement::TraversalParams makeTraversalParams(const Config& cfg, bool re
 }
 
 int runBatchPlacement(const Config& cfg) {
-    // Parse batch file (shared "reads1 [reads2] [output_prefix]" format with --meta)
     std::vector<BatchEntry> samples;
     if (!readBatchFiles(cfg.batchFile, samples)) return 1;
 
@@ -1330,7 +1303,6 @@ int runBatchPlacement(const Config& cfg) {
 
     output::info("Batch mode: {} samples", samples.size());
 
-    // Load the index once and reuse it for every sample.
     logging::debug("Loading index...");
     IndexReader reader(cfg.index, cfg.threads);
     auto idx = reader.getRoot<LiteIndex>();
@@ -1340,7 +1312,6 @@ int runBatchPlacement(const Config& cfg) {
     tree.initialize(idx.getLiteTree());
     logging::msg("Tree loaded: {} nodes", tree.allLiteNodes.size());
 
-    // Load full tree if refinement is enabled or if running alignment/genotyping
     std::unique_ptr<panmanUtils::TreeGroup> tg;
     panmanUtils::Tree* fullTreePtr = nullptr;
     bool refineEnabled = cfg.refine;
@@ -1371,8 +1342,7 @@ int runBatchPlacement(const Config& cfg) {
         placement::PlacementResult result;
         auto start = std::chrono::high_resolution_clock::now();
         placement::placeLite(result, &tree, reader, s.reads1, s.reads2, outPath, batchParams, fullTreePtr);
-        // Keep per-stage output suppressed through align/genotype too, so the first
-        // sample shows only the compact [i/N] line like the parallel samples below.
+        // Stay quiet through align/genotype so the first sample shows only the compact [i/N] line.
 
         if (result.bestLogContainmentNodeId.empty()) {
             auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
@@ -1432,7 +1402,7 @@ int runBatchPlacement(const Config& cfg) {
     }
     output::config().quiet = false;
 
-    // Process remaining samples in parallel (seed changes already loaded, tree is read-only)
+    // Remaining samples in parallel: seed changes loaded, tree is read-only.
     if (samples.size() > 1) {
         std::atomic<int> atomicSuccess(0), atomicFail(0);
         std::atomic<int> completedCount(1);  // first sample already done
@@ -1523,7 +1493,6 @@ int runBatchPlacement(const Config& cfg) {
     output::done(
         fmt::format("Batch complete: {}/{} placed in {}s", successCount, samples.size(), totalElapsed.count()));
     if (failCount > 0) logging::warn("{} samples failed placement", failCount);
-    // Non-zero exit if any sample failed, matching single-sample and metagenomic modes.
     return failCount > 0 ? 1 : 0;
 }
 
@@ -1544,7 +1513,6 @@ std::optional<placement::PlacementResult> runPlacement(const Config& cfg) {
     // --dump-all-scores needs the per-node seed scores retained after placement.
     bool storeDiagnostics = !cfg.dumpAllScores.empty();
 
-    // Load full tree if refinement is enabled (needed for genome sequences)
     std::unique_ptr<panmanUtils::TreeGroup> tg;
     panmanUtils::Tree* fullTreePtr = nullptr;
     bool refineEnabled = cfg.refine;
@@ -1584,8 +1552,7 @@ std::optional<placement::PlacementResult> runPlacement(const Config& cfg) {
         std::ofstream outFile(cfg.dumpAllScores);
         if (outFile) {
             outFile << "node\tlogRaw\tlogCosine\tcontainment\tlogContainment\n";
-            // Scores live in the per-call result (metric order 0=logRaw, 1=logCosine,
-            // 2=containment, 3=weightedContainment, 4=logContainment), indexed by node DFS index.
+            // nodeScores metric order: 0=logRaw, 1=logCosine, 2=containment, 3=weightedContainment, 4=logContainment.
             std::vector<std::pair<double, std::string>> allScores;
             for (auto& [id, node] : tree.allLiteNodes) {
                 if (!node || node->nodeIndex >= result.nodeScores.size()) continue;
@@ -1625,7 +1592,6 @@ int runAlignment(const Config& cfg, const placement::PlacementResult& placement,
         }
         T = &tg->trees[0];
     }
-    // Use LogContainment as primary placement metric
     std::string nodeId = placement.bestLogContainmentNodeId;
 
     if (nodeId.empty()) {
@@ -1654,7 +1620,6 @@ int runAlignment(const Config& cfg, const placement::PlacementResult& placement,
         outFile.close();
     }
 
-    // Create FASTA index (.fai) for htslib/samtools
     if (fai_build(refFileName.c_str()) != 0) {
         logging::err("Failed to create FASTA index for {}", refFileName);
         return 1;
@@ -1664,13 +1629,11 @@ int runAlignment(const Config& cfg, const placement::PlacementResult& placement,
 
     auto start = std::chrono::high_resolution_clock::now();
 
-    // Lightweight FASTQ reader (no seed computation)
     std::vector<std::string> readSequences, readQuals, readNames;
     seeding::readFastqPaired(readSequences, readQuals, readNames, cfg.reads1, cfg.reads2);
 
     logging::debug("Loaded {} reads", readSequences.size());
 
-    // Parallel alignment with direct BAM construction
     bool pairedEndReads = !cfg.reads2.empty();
     if (alignAndWriteBam(readSequences,
                          readQuals,
@@ -1700,7 +1663,6 @@ int runGenotyping(const Config& cfg) {
     std::string mpileupFileName = cfg.output + ".mpileup";
     std::string vcfFileName = cfg.output + ".vcf";
 
-    // Reference sequence and its contig name (node id) from the .ref.fa header.
     std::string bestMatchSequence;
     std::string refName = "ref";
     std::ifstream ref(refFileName);
@@ -1726,7 +1688,6 @@ int runGenotyping(const Config& cfg) {
     auto elapsed =
         std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::high_resolution_clock::now() - start);
 
-    // Count variant records (lines that aren't headers) for the status line.
     size_t numVariants = 0;
     {
         std::ifstream vcf(vcfFileName);
@@ -1745,7 +1706,6 @@ int runConsensus(const Config& cfg) {
     std::string vcfFileName = cfg.output + ".vcf";
     std::string consensusFileName = cfg.output + ".consensus.fa";
 
-    // Contig name (node id) from the .ref.fa header.
     std::string refName = "ref";
     {
         std::ifstream ref(refFileName);
@@ -2100,11 +2060,8 @@ int main(int argc, char** argv) {
         return 1;
     }
 
-    // Internal/ancestral nodes are eligible placement references in every stage
-    // (place -> align -> genotype -> consensus); the downstream reference is
-    // materialized from any node id, so an ancestral node closer than the best
-    // leaf improves the consensus. Pass --force-leaf to restrict to observed
-    // leaf genomes.
+    // Internal/ancestral nodes are eligible placement references in every stage; the
+    // reference is materialized from any node id. Pass --force-leaf to restrict to leaves.
 
     // The index path is always derived from the panman (placement -> .idx, metagenomic
     // -> .midx); -o does not affect it. Pass --index to load a specific pre-built index.
diff --git a/src/panmap_utils.hpp b/src/panmap_utils.hpp
index 2c81b751..9d9ea8c2 100644
--- a/src/panmap_utils.hpp
+++ b/src/panmap_utils.hpp
@@ -21,11 +21,8 @@
 
 namespace panmapUtils {
 
-// On-disk index format revision. Bump on any wire-incompatible change to
-// index_lite.capnp (e.g. widening a field's type). The placement reader rejects
-// an index whose version differs, so a stale .idx fails with a clear "rebuild"
-// message instead of a cryptic Cap'n Proto error. Pre-versioning indexes lack
-// the field and read as 0.
+// On-disk index revision; bump on any wire-incompatible change to index_lite.capnp.
+// Reader rejects a mismatched version (clear "rebuild" msg). Pre-versioning indexes read as 0.
 //   4: struct-of-arrays seed changes with 64-bit nodeChangeOffsets
 inline constexpr uint16_t INDEX_FORMAT_VERSION = 4;
 
@@ -75,9 +72,8 @@ class LiteTree {
 
     std::vector<LiteNode*> dfsIndexToNode;
 
-    // Zero-copy seed-change SoA: raw pointers into the mapped decompressed index, one
-    // per capnp segment (counts are Int16 on disk). Nodes hold (offset,size) ranges;
-    // SEED_CHANGE_SEGMENT must match the index writer's CAPNP_SPLIT.
+    // Zero-copy seed-change SoA: raw pointers into the mapped decompressed index, one per capnp
+    // segment (counts Int16). Nodes hold (offset,size) ranges; SEED_CHANGE_SEGMENT must match writer's CAPNP_SPLIT.
     static constexpr uint64_t SEED_CHANGE_SEGMENT = 500'000'000ULL;
     std::vector<const uint64_t*> segSeedHash;
     std::vector<const int16_t*> segSeedParent;
diff --git a/src/placement.cpp b/src/placement.cpp
index b7ffae86..90c166e9 100644
--- a/src/placement.cpp
+++ b/src/placement.cpp
@@ -68,7 +68,6 @@ constexpr size_t computeHomopolymerHash(char base, int k) {
     return std::min(fHash, rHash);
 }
 
-// Get all 4 canonical homopolymer hashes for a given k
 constexpr std::array<size_t, 4> getHomopolymerHashes(int k) {
     return {computeHomopolymerHash('A', k),
             computeHomopolymerHash('C', k),
@@ -76,8 +75,7 @@ constexpr std::array<size_t, 4> getHomopolymerHashes(int k) {
             computeHomopolymerHash('T', k)};
 }
 
-// Compute average Phred quality score over a k-mer span
-// Quality string uses ASCII encoding: Q = char - 33 (Phred+33)
+// Average Phred quality over a k-mer span. Phred+33 encoding: Q = char - 33.
 inline double avgPhredQuality(const std::string& qual, int64_t startPos, int k) {
     if (qual.empty() || startPos < 0 || startPos + k > static_cast<int64_t>(qual.size())) {
         return 0.0;
@@ -247,8 +245,8 @@ void placement::NodeMetrics::computeChildMetrics(placement::NodeMetrics& childMe
                                                  const placement::PlacementGlobalState& state) {
     if (seedChangeSize == 0) [[unlikely]]
         return;
-    constexpr size_t PREFETCH_DISTANCE = 24;  // deeper pipeline (L3 latency ~40 cycles)
-    constexpr size_t BATCH_SIZE = 64;         // cache-line aligned batches
+    constexpr size_t PREFETCH_DISTANCE = 24;
+    constexpr size_t BATCH_SIZE = 64;
     constexpr uint64_t SEG = panmapUtils::LiteTree::SEED_CHANGE_SEGMENT;
     const panmapUtils::LiteTree& tree = *state.liteTree;
 
@@ -264,21 +262,17 @@ void placement::NodeMetrics::computeChildMetrics(placement::NodeMetrics& childMe
         const int16_t* Pc = tree.segSeedParent[seg] + local;
         const int16_t* Cc = tree.segSeedChild[seg] + local;
 
-        // Prefetch both seed hashes and hash table buckets
         const size_t initialPrefetchCount = std::min(numChanges, PREFETCH_DISTANCE);
         for (size_t i = 0; i < initialPrefetchCount; ++i) {
             __builtin_prefetch(&H[i], 0, 0);
-            // Prefetch the table this loop actually probes (logReadCounts), not the
-            // read-processing tables that are never read here.
+            // logReadCounts is the only table this loop probes.
             state.logReadCounts.prefetch(H[i]);
         }
 
-        // Batch for instruction pipelining and cache utilization
         for (size_t batch_start = 0; batch_start < numChanges; batch_start += BATCH_SIZE) {
             const size_t batch_end = std::min(batch_start + BATCH_SIZE, numChanges);
 
             for (size_t i = batch_start; i < batch_end; ++i) {
-                // Prefetch far ahead - both data and hash table
                 if (i + PREFETCH_DISTANCE < numChanges) [[likely]] {
                     const uint64_t nextHash = H[i + PREFETCH_DISTANCE];
                     __builtin_prefetch(&H[i + PREFETCH_DISTANCE], 0, 0);
@@ -297,8 +291,8 @@ void placement::NodeMetrics::computeChildMetrics(placement::NodeMetrics& childMe
 
                 // Genome-only metrics: computed for all seed changes, even if not in reads.
 
-                // Genome magnitude squared delta: log(1+child)² - log(1+parent)²
-                // Use log-scale to match the log-scaled read vector for proper cosine similarity
+                // Genome magnitude squared delta: log(1+child)² - log(1+parent)².
+                // Log-scale to match the log-scaled read vector for proper cosine similarity.
                 const double magDelta = logChild * logChild - logParent * logParent;
                 childMetrics.genomeMagnitudeSquared += magDelta;
 
@@ -332,9 +326,8 @@ void placement::NodeMetrics::computeChildMetrics(placement::NodeMetrics& childMe
                 // Both vectors in log-space for proper cosine similarity
                 childMetrics.logCosineNumerator += logReadCount * (logChild - logParent);
 
-                // Weighted containment numerator: Σ(1/nodeGenomeCount_i) for seeds in reads ∩ genome.
-                // Weights each seed by 1/(node's genome count), rewarding genomes where matching
-                // seeds are rare/unique. Delta: 1/childCount - 1/parentCount for seeds in reads.
+                // Weighted containment numerator: Σ(1/nodeGenomeCount_i) for seeds in reads ∩ genome,
+                // upweighting genomes where matching seeds are rare. Delta: 1/childCount - 1/parentCount.
                 {
                     const double oldWcContrib = (parentCount > 0) ? (1.0 / parentCount) : 0.0;
                     const double newWcContrib = (childCount > 0) ? (1.0 / childCount) : 0.0;
@@ -357,10 +350,8 @@ using ::panmanUtils::Node;
 using ::panmanUtils::Tree;
 
 
-// Generates a score update function: updates best score/index and tracks ties.
-// Per-node scores are stored separately in PlacementResult::nodeScores (see the
-// BFS scoring block), not on the shared LiteNode, so concurrent batch placements
-// don't race.
+// Score-update fn: updates best score/index and tracks ties. Per-node scores live in
+// PlacementResult::nodeScores (not the shared LiteNode) so batch placements don't race.
 #define DEFINE_UPDATE_SCORE_FUNC(FuncName, nodeScoreField, bestScore, bestNodeIndex, tiedIndices) \
     void PlacementResult::FuncName(uint32_t nodeIndex, double score) {                            \
         double tolerance = std::max(bestScore * 0.0001, 1e-9);                                    \
@@ -491,8 +482,7 @@ std::string getNodeSequenceForRefinement(panmanUtils::Tree* T, const std::string
     return T->getStringFromReference(nodeId, false, true);
 }
 
-// Score a candidate node by aligning reads to its genome sequence
-// Returns negative total edit distance (higher = fewer errors = better)
+// Returns negative total edit distance (higher = fewer errors = better).
 // When pairedEnd=true, reads are interleaved R1_0,R2_0,R1_1,R2_1,...
 int64_t scoreNodeByAlignment(panmanUtils::Tree* fullTree,
                              const std::string& nodeId,
@@ -577,10 +567,8 @@ void refineTopCandidates(panmapUtils::LiteTree* liteTree,
     auto wContainCands = getTopForMetric([&](auto* n) { return nodeScore(n, 3); }, "WeightedContainment");
     auto logContainCands = getTopForMetric([&](auto* n) { return nodeScore(n, 4); }, "LogContainment");
 
-    // Always include the unrefined best node for each metric in its candidate set.
-    // At high coverage, seed scores saturate and the correct node may fall outside
-    // the top-N% cutoff. Including the seed-phase winner ensures refinement always
-    // considers the best unrefined placement.
+    // Always include each metric's unrefined best node: at high coverage seed scores
+    // saturate and the correct node can fall outside the top-N% cutoff.
     if (result.bestLogRawNodeIndex != UINT32_MAX) logRawCands.insert(result.bestLogRawNodeIndex);
     if (result.bestLogCosineNodeIndex != UINT32_MAX) logCosineCands.insert(result.bestLogCosineNodeIndex);
     if (result.bestContainmentNodeIndex != UINT32_MAX) containCands.insert(result.bestContainmentNodeIndex);
@@ -754,7 +742,6 @@ void placeLiteHelperBFS(std::vector<panmapUtils::LiteNode*>& nodes,
     while (!current_nodes.empty()) {
         size_t num_nodes = current_nodes.size();
 
-        // Larger chunks = less overhead, but need enough chunks for load balancing
         size_t grain_size = std::max(size_t(1), num_nodes / (numThreads * 8));
 
         // Pre-allocate empty seed counts for verification disabled case
@@ -773,12 +760,10 @@ void placeLiteHelperBFS(std::vector<panmapUtils::LiteNode*>& nodes,
 
                     if (!node) continue;
 
-                    // Software prefetch for next 4 nodes
                     constexpr size_t PREFETCH_DISTANCE = 4;
                     for (size_t j = 1; j <= PREFETCH_DISTANCE && i + j < r.end(); ++j) {
                         __builtin_prefetch(current_nodes[i + j], 0, 1);
                         __builtin_prefetch(&current_metrics[i + j], 0, 1);
-                        // seedChangeOffset/Size are POD in the node, prefetched above
                     }
 
                     batch_counter++;
@@ -823,9 +808,7 @@ void placeLiteHelperBFS(std::vector<panmapUtils::LiteNode*>& nodes,
                         tls.local_result.updateWeightedContainmentScore(nodeIndex, weightedContainmentScore);
                         tls.local_result.updateLogContainmentScore(nodeIndex, logContainmentScore);
 
-                        // Per-node scores for refinement candidate selection. Written to the
-                        // shared per-call result (not the tree) so concurrent batch placements
-                        // don't race; each node index is written by exactly one thread.
+                        // Refinement candidate scores on the per-call result; each index written by one thread.
                         if (nodeIndex < result.nodeScores.size()) {
                             result.nodeScores[nodeIndex] = {static_cast<float>(logRawScore),
                                                             static_cast<float>(logCosineScore),
@@ -949,12 +932,9 @@ int64_t resolveMinReadSupport(const absl::flat_hash_map<size_t, int64_t, Identit
                               int configuredMinSupport) {
     int64_t minSupport = configuredMinSupport;
     if (minSupport < 0) {
-        // Auto: estimate coverage from the read-count distribution (no genome length
-        // needed). A seed seen in >=2 reads is almost always a genuine genomic k-mer
-        // (random errors rarely recur across reads), and its read count approximates
-        // local depth, so the mean over these seeds estimates coverage. Below ~3x most
-        // true seeds are singletons and must be kept (1); above it singletons are
-        // overwhelmingly errors, so require >=2.
+        // Auto: a seed in >=2 reads is almost always genuine (errors rarely recur), so the
+        // mean read-count over such seeds estimates coverage. Below ~3x keep singletons (1);
+        // above it they are overwhelmingly errors, so require >=2.
         uint64_t multiSeedFreqSum = 0;
         uint64_t multiSeedCount = 0;
         for (const auto& [seedHash, readCount] : seedFreqInReads) {
@@ -1028,9 +1008,8 @@ void placeLite(PlacementResult& result,
 
     auto indexRoot = liteIndex.getRoot<LiteIndex>();
 
-    // Reject a stale index before reading any width-sensitive field (the
-    // nodeChangeOffsets element width changed with the format), so an old .idx
-    // fails with a clear rebuild message instead of a cryptic capnp error.
+    // Reject a stale index before reading any width-sensitive field (nodeChangeOffsets
+    // element width changed with the format), so old .idx gives a clear rebuild message.
     if (indexRoot.getFormatVersion() != panmapUtils::INDEX_FORMAT_VERSION) {
         throw std::runtime_error(fmt::format(
             "Index format version {} is incompatible with this panmap (expects {}). "
@@ -1042,7 +1021,6 @@ void placeLite(PlacementResult& result,
     if (!liteTree->seedChangesLoaded) {
         logging::debug("Loading pre-computed hash deltas from index for {} nodes...", liteTree->allLiteNodes.size());
 
-        // Process nodes in DFS order with direct vector indexing: O(1) access, no hash-map lookup in hot path.
         const size_t numNodes = liteTree->allLiteNodes.size();
 
         // Parallel Pass 1: Count seed changes per node to calculate offsets
@@ -1069,9 +1047,8 @@ void placeLite(PlacementResult& result,
             }
             totalHashDeltas = nodeOffsets[numNodes];
 
-            // Zero-copy: point into the decompressed index (kept mapped for the tree's
-            // lifetime) via toAny(list).getRawBytes() (contiguous little-endian data)
-            // instead of copying every seed-change tuple into a flat array.
+            // Zero-copy: point into the decompressed index (mapped for the tree's lifetime)
+            // via toAny(list).getRawBytes() (contiguous little-endian), not a copied array.
             static_assert(panmapUtils::LiteTree::SEED_CHANGE_SEGMENT == 500'000'000ULL,
                           "SEED_CHANGE_SEGMENT must match the index writer's CAPNP_SPLIT");
             auto hashesReader = indexRoot.getSeedChangeHashes();
@@ -1163,10 +1140,8 @@ void placeLite(PlacementResult& result,
             }
         }
 
-        // Apply homopolymer compression to reads if the index was built with HPC.
-        // When quality filtering is active, compress each quality string in lockstep
-        // (keep the first base's quality per run) so per-seed quality lookups stay
-        // aligned with the compressed sequence coordinates.
+        // HPC-compress reads if the index used HPC; compress each quality string in lockstep
+        // (first base's quality per run) so per-seed quality lookups stay aligned.
         if (params.hpc && !allReadSequences.empty()) {
             logging::info("HPC mode: compressing read sequences");
             const bool compressQual = params.minSeedQuality > 0 && !allReadQualities.empty();
@@ -1348,13 +1323,10 @@ void placeLite(PlacementResult& result,
                     size_t num_cpus = tbb::global_control::active_value(tbb::global_control::max_allowed_parallelism);
                     std::vector<absl::flat_hash_map<size_t, int64_t>> threadLocalMaps(num_cpus);
 
-                    // Pre-allocate capacity to eliminate malloc overhead (~14% of time in malloc).
-                    // Formula: seeds/read * reads/thread * load_factor_headroom.
-                    const size_t avg_seeds_per_read = 50;  // Conservative estimate for syncmers
+                    const size_t avg_seeds_per_read = 50;
                     const size_t reads_per_thread = (dupReadsIndex.size() + num_cpus - 1) / num_cpus;
                     const size_t estimated_seeds = avg_seeds_per_read * reads_per_thread;
-                    // Reserve 1.5x for hash table load factor (typically 0.875 max)
-                    const size_t reserve_capacity = (estimated_seeds * 3) / 2;
+                    const size_t reserve_capacity = (estimated_seeds * 3) / 2;  // 1.5x for load factor
 
                     for (auto& localMap : threadLocalMaps) {
                         localMap.reserve(reserve_capacity);
@@ -1652,10 +1624,8 @@ void placeLite(PlacementResult& result,
 
                             if (syncmers.size() < static_cast<size_t>(params.l)) continue;
 
-                            // Primer-trim: keep only syncmers whose k-mer start is within
-                            // [validStart, validEnd]. Trimming removes contiguous end syncmers,
-                            // so the in-range set is the sub-range [loIdx, hiIdx). No-op when
-                            // trimStart/trimEnd == 0.
+                            // Primer-trim: keep syncmers with k-mer start in [validStart, validEnd]
+                            // (a sub-range [loIdx, hiIdx) since trimming removes contiguous ends).
                             const int seqLen = static_cast<int>(seq.size());
                             const int validStart = params.trimStart;
                             const int validEnd = seqLen - params.trimEnd - params.k;
@@ -1888,9 +1858,8 @@ void placeLite(PlacementResult& result,
     state.root = liteTree->root;
     state.liteTree = liteTree;  // zero-copy seed-change SoA pointers used by computeChildMetrics
 
-    // Precompute inverse genome counts from root's seed changes
-    // g_i = number of genomes containing seed i (root's childCount for that seed)
-    // Used by weighted containment metric to upweight rare/discriminative seeds
+    // Inverse genome counts from root's seed changes: g_i = genomes containing seed i
+    // (root's childCount). Weighted containment uses these to upweight rare seeds.
     if (liteTree->root) {
         liteTree->forEachSeedChange(liteTree->root->seedChangeOffset,
                                     liteTree->root->seedChangeSize,
@@ -1925,9 +1894,8 @@ void placeLite(PlacementResult& result,
             root_level_seed_counts.emplace_back();
         }
 
-        // Refinement (and --dump-all-scores) read per-node seed scores back;
-        // allocate the per-call store (indexed by node DFS index) so the BFS can
-        // fill it without touching the shared tree. Skipped when nothing reads it.
+        // Refinement (and --dump-all-scores) read per-node seed scores back; allocate the
+        // per-call store (by DFS index) so the BFS fills it without touching the shared tree.
         if (params.refineEnabled || params.store_diagnostics) {
             result.nodeScores.assign(liteTree->dfsIndexToNode.size(), {});
         }
@@ -1936,7 +1904,7 @@ void placeLite(PlacementResult& result,
         placeLiteHelperBFS(
             root_level_nodes, root_level_metrics, root_level_seed_counts, state, result, params, nodesProcessed);
 
-        // Lazy ID resolution: only deserialize winning node IDs (eliminates ~1800ms overhead)
+        // Lazy ID resolution: deserialize only the winning node IDs
         result.resolveNodeIds(liteTree);
 
         // Optional refinement: re-score top candidates by full minimap2 alignment.
diff --git a/src/placement.hpp b/src/placement.hpp
index 59c7da8f..d8354cc6 100644
--- a/src/placement.hpp
+++ b/src/placement.hpp
@@ -25,25 +25,24 @@ namespace placement {
 struct PlacementResult;
 struct PlacementGlobalState;
 
-// Parameters for lite placement traversal
 struct TraversalParams {
     int k = 19;                       // k-mer size
-    int s = 8;                        // syncmer parameter s
-    int t = 0;                        // t-syncmer parameter
-    int l = 3;                        // k-minimizer window size (1 = use raw syncmers)
-    bool open = false;                // use open syncmers
-    bool verify_scores = false;       // recompute scores from scratch for verification
-    bool store_diagnostics = false;   // store metric components on nodes for diagnostic output
-    double seedMaskFraction = 0.001;  // Mask top N fraction of seeds by frequency (0 = disabled, 0.001 = top 0.1%)
-    int minSeedQuality = 0;           // Min avg Phred quality for seed region (0 = disabled)
-    bool dedupReads = false;          // Deduplicate reads before placement (count each unique sequence once)
+    int s = 8;
+    int t = 0;
+    int l = 3;                        // 1 = raw syncmers, not k-minimizers
+    bool open = false;
+    bool verify_scores = false;
+    bool store_diagnostics = false;
+    double seedMaskFraction = 0.001;  // 0 = disabled; else mask top fraction of seeds by frequency
+    int minSeedQuality = 0;           // min avg Phred over seed span; 0 = disabled
+    bool dedupReads = false;
     bool pairFilter =
-        true;           // Filter: only count seeds from read-pairs that have at least one matching seed at current node
-    int trimStart = 0;  // Trim N bases from start of each read before seeding (for primer removal)
-    int trimEnd = 0;    // Trim N bases from end of each read before seeding (for primer removal)
+        true;           // only count seeds from read-pairs with >=1 matching seed at current node
+    int trimStart = 0;  // bases trimmed from read start (primer removal)
+    int trimEnd = 0;    // bases trimmed from read end (primer removal)
     int minReadSupport =
-        -1;            // Min read count for a seed; -1 = auto (2 if est. coverage > 3x, else 1), 1 = all seeds, 2 = filter singletons
-    bool hpc = false;  // Homopolymer-compressed seeds (from index)
+        -1;            // -1 = auto (2 if est. coverage > 3x, else 1); 1 = keep all; 2 = drop singletons
+    bool hpc = false;
 
     // Alignment-based refinement: after k-mer scoring, optionally refine top candidates by full alignment
     bool refineEnabled = false;
@@ -54,7 +53,6 @@ struct TraversalParams {
     bool forceLeaf = false;        // Restrict scoring to leaf nodes only
 };
 
-// Track global state during placement
 struct PlacementGlobalState {
     // Seed hash frequency map from reads (computed once, used for all nodes)
     absl::flat_hash_map<size_t, int64_t, IdentityHash> seedFreqInReads;
@@ -96,21 +94,18 @@ struct PlacementGlobalState {
     bool forceLeaf = false;
 };
 
-// Resolve the effective minimum read-count support for a seed. configuredMinSupport < 0
-// means "auto": 2 when estimated coverage (mean read count over seeds seen in >=2 reads)
-// exceeds 3x, else 1. Logs the auto decision.
+// Effective min read-count support for a seed. configuredMinSupport < 0 means "auto":
+// 2 when est. coverage (mean read count over seeds seen in >=2 reads) exceeds 3x, else 1.
 int64_t resolveMinReadSupport(const absl::flat_hash_map<size_t, int64_t, IdentityHash>& seedFreqInReads,
                               int configuredMinSupport);
 
-// Fill the read-derived scoring fields of `state` from state.seedFreqInReads, keeping only
-// seeds with read count >= minSupport: logReadCounts, totalReadSeedFrequency,
-// readUniqueSeedCount, logReadMagnitude, logContainmentDenominator. Returns the number of
-// seeds the filter dropped.
+// Fill state's read-derived scoring fields (logReadCounts, totalReadSeedFrequency,
+// readUniqueSeedCount, logReadMagnitude, logContainmentDenominator) from seedFreqInReads,
+// keeping only seeds with read count >= minSupport. Returns count of dropped seeds.
 size_t computeReadSeedMagnitudes(PlacementGlobalState& state, int64_t minSupport);
 
 // Delta-based metrics (forward-only traversal)
 struct NodeMetrics {
-    // Read-genome interaction metrics (computed incrementally)
     double logRawNumerator = 0.0;               // Σ(log(1+readCount) / genomeCount) for LogRAW metric
     double logCosineNumerator = 0.0;            // Σ(log(1+readCount) × genomeCount) for LogCosine metric
     size_t presenceIntersectionCount = 0;       // Count of seeds present in both read and genome
@@ -153,43 +148,35 @@ struct NodeMetrics {
         return (logContainmentDenominator > 0.0) ? logContainmentNumerator / logContainmentDenominator : 0.0;
     }
 
-    // Compute child metrics from parent metrics + seed changes
     static void computeChildMetrics(NodeMetrics& childMetrics,
                                     uint64_t seedChangeOffset,
                                     uint32_t seedChangeSize,
                                     const PlacementGlobalState& state);
 };
 
-// Consolidated score tracking and results for lite placement
 struct PlacementResult {
-    // LogRAW Score results (log-scaled, coverage-robust)
     double bestLogRawScore = 0.0;
     uint32_t bestLogRawNodeIndex = UINT32_MAX;
     std::vector<uint32_t> tiedLogRawNodeIndices;
 
-    // LogCosine Score results (log-scaled cosine similarity)
     double bestLogCosineScore = 0.0;
     uint32_t bestLogCosineNodeIndex = UINT32_MAX;
     std::vector<uint32_t> tiedLogCosineNodeIndices;
 
-    // Containment Index results
     double bestContainmentScore = 0.0;
     uint32_t bestContainmentNodeIndex = UINT32_MAX;
     std::vector<uint32_t> tiedContainmentNodeIndices;
 
-    // Weighted Containment Index results
     double bestWeightedContainmentScore = 0.0;
     uint32_t bestWeightedContainmentNodeIndex = UINT32_MAX;
     std::vector<uint32_t> tiedWeightedContainmentNodeIndices;
 
-    // Log Containment Index results
     double bestLogContainmentScore = 0.0;
     uint32_t bestLogContainmentNodeIndex = UINT32_MAX;
     std::vector<uint32_t> tiedLogContainmentNodeIndices;
 
-    // Per-call, per-node seed scores indexed by node DFS index; only populated
-    // when refinement is enabled. Kept here rather than on the shared LiteNode so
-    // concurrent batch placements don't race. Metric order:
+    // Per-node seed scores by DFS index (populated only when refinement enabled). Kept here
+    // not on the shared LiteNode so concurrent batch placements don't race. Metric order:
     // {logRaw, logCosine, containment, weightedContainment, logContainment}.
     std::vector<std::array<float, 5>> nodeScores;
 
diff --git a/src/progress_tracker.hpp b/src/progress_tracker.hpp
index 538dcf8c..8cfba7d8 100644
--- a/src/progress_tracker.hpp
+++ b/src/progress_tracker.hpp
@@ -7,7 +7,6 @@
 #include <numeric>
 #include "logging.hpp"
 
-// Aggregates per-thread progress into a single progress bar.
 class ProgressTracker {
    public:
     ProgressTracker(size_t numThreads, const std::vector<uint64_t>& totalNodesPerThread)
@@ -25,7 +24,6 @@ class ProgressTracker {
         publish();
     }
 
-    // Flush final progress, then clear the bar.
     void finalDisplay() {
         if (!bar_) return;
         uint64_t totalProgress = 0;
diff --git a/src/seeding.cpp b/src/seeding.cpp
index ea89e2e4..2e365ec7 100644
--- a/src/seeding.cpp
+++ b/src/seeding.cpp
@@ -29,10 +29,7 @@ std::pair<size_t, size_t> hashSeq(const std::string& s) {
     return std::make_pair(fHash, rHash);
 }
 
-// Fixed-capacity ring buffer for the s-mer hash window in rollingSyncmers. The window is
-// exactly k-s+1 wide (one pop + one push per roll), so a contiguous buffer allocated once
-// replaces std::deque's per-op chunk management -- a hot spot in read/index seeding. Only
-// the deque operations rollingSyncmers actually uses are provided; behaviour is identical.
+// Ring buffer (width k-s+1) replacing std::deque to avoid per-roll allocation.
 namespace {
 struct SmerRing {
     std::vector<size_t> buf;
diff --git a/src/seeding.hpp b/src/seeding.hpp
index 6d8ae5c6..0cb78465 100644
--- a/src/seeding.hpp
+++ b/src/seeding.hpp
@@ -2,7 +2,7 @@
 
 #include <cstdint>
 #if defined(__x86_64__) || defined(_M_X64) || defined(__i386__)
-#include <immintrin.h>  // x86-only SIMD intrinsics
+#include <immintrin.h>
 #endif
 
 #include <algorithm>
@@ -28,7 +28,7 @@ KSEQ_INIT(int, read)
 
 namespace seeding {
 
-// Perfect shuffle for interleaving paired-end reads (R1_0, R2_0, R1_1, R2_1, ...)
+// Interleave paired-end reads: R1_0, R2_0, R1_1, R2_1, ...
 template <typename T>
 inline void perfect_shuffle(std::vector<T>& v) {
     const size_t n = v.size();
@@ -69,15 +69,14 @@ struct uniqueKminmer_t {
     }
 };
 
-// A syncmer seed within a single sequence
 struct seed_t {
     size_t hash;
-    int64_t pos;    // Position in sequence
-    int32_t idx;    // Index in vector, set during indexing
+    int64_t pos;
+    int32_t idx;    // set during indexing
     bool reversed;
-    uint32_t rpos;  // Position on reference, set during alignment
+    uint32_t rpos;  // set during alignment
 
-    int64_t endPos;  // End position, counting gaps
+    int64_t endPos;  // counting gaps
 
     bool operator<(const seed_t& rhs) const { return pos < rhs.pos; }
 
@@ -129,9 +128,7 @@ rollingSyncmers(std::string_view seq, int k, int s, bool open, int t = 0, bool r
 
 std::string reverseComplement(std::string dna_sequence);
 
-// Reads sequences, qualities, and names without computing seeds.
-// For paired-end (fastqPath2 non-empty): RC's R2 sequences and interleaves pairs
-// (R1_0, R2_0, R1_1, R2_1, ...).
+// Paired-end (fastqPath2 set): reverse-complements R2 and interleaves pairs.
 void readFastqPaired(std::vector<std::string>& readSequences,
                      std::vector<std::string>& readQuals,
                      std::vector<std::string>& readNames,
@@ -141,8 +138,7 @@ void readFastqPaired(std::vector<std::string>& readSequences,
 // Homopolymer compression: collapse consecutive identical bases (e.g., AAACGG -> ACG)
 std::string hpcCompress(const std::string& seq);
 
-// HPC with position mapping: returns (compressed_seq, mapping) where
-// mapping[i] = index in original seq of the i-th base in compressed seq
+// mapping[i] = index in original seq of the i-th base in the compressed seq
 std::pair<std::string, std::vector<size_t>> hpcCompressWithMapping(const std::string& seq);
 
 }  // namespace seeding
diff --git a/src/test/helpers/metrics_oracle.hpp b/src/test/helpers/metrics_oracle.hpp
index 9b3dc18c..04261f17 100644
--- a/src/test/helpers/metrics_oracle.hpp
+++ b/src/test/helpers/metrics_oracle.hpp
@@ -1,19 +1,13 @@
 #pragma once
 
 /**
- * @brief Independent ground-truth oracle for placement metrics.
- *
- * Reproduces the five placement scores exactly:
- *   (a) per-seed numerators use the same formulas as
- *       placement::NodeMetrics::computeChildMetrics (placement.cpp:206-260);
- *   (b) denominators come from the live PlacementGlobalState, which already encodes
- *       the minReadSupport read filter and the root-derived inverse genome counts.
- * Denominators are read from state rather than recomputed, so (live getter == oracle)
- * holds within float epsilon.
+ * Independent ground-truth oracle for placement metrics. Numerators use the same formulas as
+ * placement::NodeMetrics::computeChildMetrics (placement.cpp:206-260); denominators are read
+ * from the live PlacementGlobalState (not recomputed), so live getter == oracle within epsilon.
  *
  * Formulas (verbatim from placement.cpp computeChildMetrics):
  *   genomeMagnitudeSquared        = Σ_{seed∈genome}            log(1+gc)²            (placement.cpp:215)
- *   logRawNumerator               = Σ_{seed∈reads∩genome}      log(1+rc) / gc        (placement.cpp:240-242, RAW gc)
+ *   logRawNumerator               = Σ_{seed∈reads∩genome}      log(1+rc) / gc        (placement.cpp:240-242, raw gc)
  *   logCosineNumerator            = Σ_{seed∈reads∩genome}      log(1+rc) · log(1+gc) (placement.cpp:246)
  *   weightedContainmentNumerator  = Σ_{seed∈reads∩genome}      1 / gc                (placement.cpp:253-255, node gc)
  *   logContainmentNumerator       = Σ_{seed∈reads∩genome}      log(1+rc)             (placement.cpp:260)
@@ -41,13 +35,8 @@ struct GroundTruthMetrics {
     double logContainmentNumerator = 0.0;
     size_t presenceIntersectionCount = 0;
 
-    /**
-     * @brief Compute numerators from a node's reconstructed genome seed set and the
-     *        live placement state, which supplies the filtered read seeds.
-     *
-     * @param nodeGenome  hash -> genome count for this node (from reconstructGenomeSeeds)
-     * @param state       the running PlacementGlobalState (filtered reads + log counts)
-     */
+    // Compute numerators from a node's reconstructed genome seeds (hash -> genome count) and
+    // the live placement state, which supplies the filtered read seeds.
     static GroundTruthMetrics compute(const SeedCountMap& nodeGenome, const placement::PlacementGlobalState& state);
 
     // The five scores, each divided by the live denominator in state.
diff --git a/src/test/helpers/seed_helpers.hpp b/src/test/helpers/seed_helpers.hpp
index 0ef3a452..f7c53df2 100644
--- a/src/test/helpers/seed_helpers.hpp
+++ b/src/test/helpers/seed_helpers.hpp
@@ -14,9 +14,8 @@
 
 namespace ts {
 
-// Extract syncmer seeds from a sequence the same way the read/genome paths do:
-// rollingSyncmers(seq, k, s, open=false, t=0), counting only flagged syncmers.
-// countDuplicates=true accumulates frequency; false collapses to presence (count 1).
+// Extract syncmer seeds as the read/genome paths do: rollingSyncmers(seq, k, s, open=false, t=0),
+// counting only flagged syncmers. countDuplicates=false collapses to presence (count 1).
 indexUtils::SeedCountMap extractSeeds(std::string_view seq, int k, int s, bool countDuplicates = true);
 
 // Read a FASTA file and return the concatenated sequence (ignores headers/whitespace).
diff --git a/src/test/helpers/test_index.hpp b/src/test/helpers/test_index.hpp
index 688ad31a..dce8283e 100644
--- a/src/test/helpers/test_index.hpp
+++ b/src/test/helpers/test_index.hpp
@@ -17,10 +17,8 @@
 
 namespace ts {
 
-// Owns a loaded index. LiteIndex seed-change struct-of-arrays are stored segmented as
-// List(List(...)) in the file, and flattened into plain vectors on load so tests address
-// them by a flat index without touching capnp readers or re-traversing the message.
-// LiteTree is self-contained after initialize() (copies structure).
+// Owns a loaded index. Segmented seed-change SoA (List(List(...)) in the file) is flattened
+// into plain vectors on load so tests address seeds by a flat index. LiteTree self-contained.
 class IndexData {
    public:
     std::unique_ptr<panmapUtils::LiteTree> liteTree;
@@ -77,10 +75,8 @@ class TestIndex {
     IndexData data_;
 };
 
-// Lazily-built, shared, READ-ONLY rsv_4K fixture and its k=15/s=8/t=0/l=1 index. Boost.Test
-// runs a binary's cases serially in one process, so one load+build is reused across cases
-// rather than repeated per case (the fixture load + full index build is the dominant unit-test
-// cost). NEVER use these from a test that MUTATES the tree -- build your own there.
+// Lazily-built, shared, read-only rsv_4K fixture and its k=15/s=8/t=0/l=1 index, reused across
+// cases (load+build dominates unit-test cost). Don't use from a test that mutates the tree.
 const RSVPanmanFixture& sharedRSVFixture();
 const IndexData& sharedRSVIndex();
 
diff --git a/src/test/test_index.cpp b/src/test/test_index.cpp
index 36db122a..7df34106 100644
--- a/src/test/test_index.cpp
+++ b/src/test/test_index.cpp
@@ -1,5 +1,3 @@
-// Index round-trip tests: structural integrity and delta reconstruction equals
-// direct genome seed extraction.
 #include <boost/test/unit_test.hpp>
 
 #include "helpers/seed_helpers.hpp"
@@ -14,8 +12,7 @@
 #include <vector>
 
 namespace {
-// Params for comparison against raw rollingSyncmers extraction: l=1 (kminmers ==
-// syncmers) and flankMaskBp=0 (no masking), matching extractSeeds.
+// l=1 (kminmers == syncmers), flankMaskBp=0 (no masking): matches extractSeeds.
 constexpr int K = 15, S = 8, L = 1;
 
 std::vector<std::string> sampleNodeIds(const ts::RSVPanmanFixture& fix, int n, uint64_t seed) {
@@ -30,8 +27,7 @@ std::vector<std::string> sampleNodeIds(const ts::RSVPanmanFixture& fix, int n, u
 BOOST_AUTO_TEST_SUITE(index_tests)
 
 BOOST_AUTO_TEST_CASE(index_parameters_persisted) {
-    // Non-default params (differ from sharedRSVIndex's 15/8/0/1) prove the values aren't
-    // hardcoded; built over the shared tree to skip a second fixture load.
+    // Non-default params (vs sharedRSVIndex's 15/8/0/1) prove the values aren't hardcoded.
     ts::TestIndex idx(ts::sharedRSVFixture().tree(), /*k=*/19, /*s=*/6, /*t=*/0, /*l=*/3);
     const auto& d = idx.data();
     BOOST_TEST(d.k == 19);
@@ -51,13 +47,11 @@ BOOST_AUTO_TEST_CASE(offset_and_parent_child_consistency) {
     BOOST_TEST(d.nodeChangeOffset(0) == 0u);
     BOOST_TEST(d.nodeChangeOffset(numOffsets - 1) == d.numChanges());
 
-    // Monotonic non-decreasing offsets.
     for (size_t i = 1; i < numOffsets; ++i) {
         BOOST_REQUIRE(d.nodeChangeOffset(i) >= d.nodeChangeOffset(i - 1));
     }
 
-    // Along several root->node paths, each change's parentCount must equal the
-    // running (child) count established by the previous change for that seed.
+    // Each change's parentCount must equal the running (child) count from the previous change for that seed.
     const auto& tree = *d.liteTree;
     int inconsistencies = 0;
     for (const auto& nodeId : sampleNodeIds(fix, 8, 13)) {
@@ -99,9 +93,8 @@ BOOST_AUTO_TEST_CASE(delta_reconstruction_equals_direct) {
         std::string genome = fix.genomeOf(nodeId);
         auto direct = ts::extractSeeds(genome, K, S, /*countDuplicates=*/true);
 
-        // N-imputation can only add seeds (N breaks syncmers in direct extraction but
-        // imputed bases preserve them), so every direct seed must appear in the
-        // reconstruction with the same count; the reconstruction may have extras.
+        // N-imputation only adds seeds (N breaks syncmers in direct extraction, imputed bases
+        // preserve them), so every direct seed appears in the reconstruction; extras are allowed.
         const bool genomeHasN = genome.find('N') != std::string::npos;
         for (const auto& [h, count] : direct) {
             auto it = reconstructed.find(h);
@@ -116,8 +109,6 @@ BOOST_AUTO_TEST_CASE(delta_reconstruction_equals_direct) {
     }
 }
 
-// buildIndexParallel (the -t path) must yield the same reconstructed genome seeds
-// as the sequential builder.
 BOOST_AUTO_TEST_CASE(parallel_build_matches_single_thread) {
     const auto& fix = ts::sharedRSVFixture();
     const auto& ds = ts::sharedRSVIndex();   // the shared index IS the sequential (1-thread) build
@@ -147,14 +138,10 @@ BOOST_AUTO_TEST_CASE(parallel_build_matches_single_thread) {
     }
 }
 
-// rsv_4K contains no block inversions, so the strand-flip whole-block seed
-// recompute (computeNewSyncmerRangesJump, index_single_mode.cpp ~line 307) is
-// otherwise untested. Inject synthetic pure block inversions (blockMutInfo=false,
-// inversion=true, how panman encodes an inversion) into a sample of leaf nodes,
-// each inverting an existing block, then assert the incremental index seeds equal
-// from-scratch extraction. Injecting only at leaves keeps each injection
-// independent, so non-injected leaves are controls.
-// (Also validated against 89 real inversions in tb_400.panman, all matching.)
+// rsv_4K has no block inversions, so the strand-flip seed recompute (computeNewSyncmerRangesJump,
+// index_single_mode.cpp ~line 307) is otherwise untested. Inject synthetic pure inversions at
+// leaves, assert incremental seeds == from-scratch. Also validated against 89 real inversions in
+// tb_400.panman.
 BOOST_AUTO_TEST_CASE(block_inversion_reconstruction_equals_direct) {
     ts::RSVPanmanFixture fix;
     panmanUtils::Tree* T = fix.tree();
@@ -166,9 +153,8 @@ BOOST_AUTO_TEST_CASE(block_inversion_reconstruction_equals_direct) {
     std::mt19937_64 g(7);
     std::shuffle(leaves.begin(), leaves.end(), g);
 
-    // Inject a pure inversion of the largest existing forward block (length >= k, so
-    // the flip changes seeds) into the first N leaves; the rest are controls. Record
-    // each pre-injection genome to confirm the injections change the genome.
+    // Inject an inversion of the largest forward block (>= k, so the flip changes seeds) into the
+    // first N leaves; rest are controls. Record pre-injection genomes.
     std::vector<std::string> injected, controls;
     std::unordered_map<std::string, std::string> genomeBefore;
     const size_t kInject = 25;
@@ -181,9 +167,8 @@ BOOST_AUTO_TEST_CASE(block_inversion_reconstruction_equals_direct) {
         std::vector<char> blockExists, blockStrand;
         std::unordered_map<int, int> blockLengths;
         panmapUtils::getSequenceFromReference(T, seq, blockExists, blockStrand, blockLengths, id);
-        // For an existing block, getSequenceFromReference fills seq[b] with the block's
-        // nucleotides (blockLengths is only tracked for absent blocks). Pick the largest
-        // existing forward block; inverting it flips >= k bases so seeds change.
+        // getSequenceFromReference fills seq[b] with an existing block's nucleotides (blockLengths
+        // tracks only absent blocks). Pick the largest forward block (>= k bases).
         int best = -1, bestLen = 0;
         for (size_t b = 0; b < blockExists.size() && b < seq.size(); ++b) {
             if (!blockExists[b] || !blockStrand[b]) continue;
@@ -209,12 +194,11 @@ BOOST_AUTO_TEST_CASE(block_inversion_reconstruction_equals_direct) {
     BOOST_TEST_MESSAGE("injected pure inversions into " << injected.size() << " leaves; controls=" << controls.size());
     BOOST_REQUIRE(!injected.empty());
 
-    // Build the index from the mutated tree (imputeAmb=false; flankMaskBp=0; l=1 => seeds==syncmers).
+    // Build the index from the mutated tree.
     ts::TestIndex idx(T, K, S, 0, L, /*open=*/false, /*hpc=*/false, /*flankMaskBp=*/0);
     auto& d = idx.data();
     const auto& tree = *d.liteTree;
 
-    // Confirm the injections changed the genomes (not no-ops).
     int meaningful = 0;
     for (const auto& id : injected) {
         if (T->getStringFromReference(id, false) != genomeBefore[id]) meaningful++;
@@ -272,9 +256,7 @@ BOOST_AUTO_TEST_CASE(block_inversion_reconstruction_equals_direct) {
     long invMism = 0, invMiss = 0, invExtra = 0;
     runSet("INJECTED-INVERSION", injected, kInject, invMism, invMiss, invExtra);
 
-    // The correctness contract must hold for inversion nodes as it does for control
-    // nodes. Control is the baseline (should be 0); any inversion-specific
-    // missing/extra above that baseline is a seed-recompute defect.
+    // Inversion nodes must satisfy the same contract as controls (baseline 0); any excess is a seed-recompute defect.
     BOOST_TEST(ctrlMiss == 0);
     BOOST_TEST(ctrlExtra == 0);
     BOOST_TEST(invMiss == 0);
diff --git a/src/test/test_placement.cpp b/src/test/test_placement.cpp
index 87327235..302c6caf 100644
--- a/src/test/test_placement.cpp
+++ b/src/test/test_placement.cpp
@@ -1,5 +1,3 @@
-// Placement metric tests. The live NodeMetrics getters must equal the independent
-// GroundTruthMetrics oracle within float epsilon. Genome equality is covered in test_index.
 #include <boost/test/unit_test.hpp>
 
 #include "placement.hpp"
@@ -19,9 +17,7 @@ const std::string kTruthNode = "MZ515733.1";
 
 using Change = std::tuple<uint64_t, int64_t, int64_t>;  // (hash, parentCount, childCount)
 
-// Build a PlacementGlobalState from a read seed set, computing the same denominators
-// the live getters and the oracle both divide by. Sharing this state isolates the
-// numerator logic: computeChildMetrics vs oracle::compute.
+// Denominators match what the live getters and oracle both divide by, isolating numerators.
 placement::PlacementGlobalState makeState(const indexUtils::SeedCountMap& readSeeds,
                                           const indexUtils::SeedCountMap& rootGenome) {
     placement::PlacementGlobalState state;
@@ -46,8 +42,6 @@ placement::PlacementGlobalState makeState(const indexUtils::SeedCountMap& readSe
     return state;
 }
 
-// Adapt hand-built seed changes to the zero-copy SoA API: build a single-segment
-// LiteTree view over the changes and call computeChildMetrics.
 void computeChildMetricsFor(placement::NodeMetrics& m,
                             const std::vector<Change>& changes,
                             placement::PlacementGlobalState& state) {
@@ -91,20 +85,19 @@ placement::NodeMetrics accumulateAlongPath(const ts::IndexData& d,
 
 BOOST_AUTO_TEST_SUITE(placement_tests)
 
-// Hand-built seed-change spans run through computeChildMetrics, checked against the oracle.
 BOOST_AUTO_TEST_CASE(child_metrics_unit_cases) {
     const uint64_t H = 0xAAAA;  // a read seed
     const uint64_t X = 0xBBBB;  // not a read seed
 
     placement::PlacementGlobalState state;
-    state.logReadCounts[H] = std::log1p(3.0);  // read count 3
+    state.logReadCounts[H] = std::log1p(3.0);
     state.seedFreqInReads[H] = 3;
     state.readUniqueSeedCount = 1;
-    state.logReadMagnitude = std::log1p(3.0);  // single seed
+    state.logReadMagnitude = std::log1p(3.0);
     state.logContainmentDenominator = std::log1p(3.0);
     state.weightedContainmentDenominator = 1.0;
 
-    // (a) H appears in genome (0 -> 2): all read-interaction numerators update.
+    // (a) H in genome (0 -> 2).
     {
         std::vector<Change> ch = {{H, 0, 2}};
         placement::NodeMetrics m;
@@ -119,10 +112,7 @@ BOOST_AUTO_TEST_CASE(child_metrics_unit_cases) {
             m.getLogContainmentScore(state.logContainmentDenominator), oracle.logContainmentScore(state), 1e-3);
         BOOST_CHECK_EQUAL(m.presenceIntersectionCount, 1u);
 
-        // Hand-derived ground truth for r=3, g=2 (independently verified, not via the
-        // oracle): logRaw = log(4)/2 / log(4) = 0.5; logCosine = log(4)log(3) /
-        // (log(4)·log(3)) = 1; containment = 1/1 = 1; weightedContainment = (1/2)/1 =
-        // 0.5; logContainment = log(4)/log(4) = 1.
+        // Hand-derived for r=3, g=2: logRaw=0.5, logCosine=1, containment=1, weightedContainment=0.5, logContainment=1.
         BOOST_CHECK_CLOSE(m.getLogRawScore(state.logReadMagnitude), 0.5, 1e-3);
         BOOST_CHECK_CLOSE(m.getLogCosineScore(state.logReadMagnitude), 1.0, 1e-3);
         BOOST_CHECK_CLOSE(m.getContainmentScore(state.readUniqueSeedCount), 1.0, 1e-3);
@@ -130,18 +120,17 @@ BOOST_AUTO_TEST_CASE(child_metrics_unit_cases) {
         BOOST_CHECK_CLOSE(m.getLogContainmentScore(state.logContainmentDenominator), 1.0, 1e-3);
     }
 
-    // (b) Only a non-read seed X changes: read-interaction numerators stay 0,
-    //     but genome magnitude still updates.
+    // (b) Only non-read seed X changes: read numerators stay 0, genome magnitude still updates.
     {
         std::vector<Change> ch = {{X, 0, 5}};
         placement::NodeMetrics m;
         computeChildMetricsFor(m, ch, state);
         BOOST_CHECK_SMALL(m.getLogRawScore(state.logReadMagnitude), 1e-12);
         BOOST_CHECK_EQUAL(m.presenceIntersectionCount, 0u);
-        BOOST_CHECK_GT(m.genomeMagnitudeSquared, 0.0);  // genome-only metric updated
+        BOOST_CHECK_GT(m.genomeMagnitudeSquared, 0.0);
     }
 
-    // (c) freqDelta == 0 but seed present (2 -> 2): no-op for every metric.
+    // (c) freqDelta == 0, seed present (2 -> 2): no-op for every metric.
     {
         std::vector<Change> ch = {{H, 2, 2}};
         placement::NodeMetrics m;
@@ -152,9 +141,6 @@ BOOST_AUTO_TEST_CASE(child_metrics_unit_cases) {
     }
 }
 
-// Multi-seed cases with hand-derived expected scores, independent of the oracle:
-// accumulation over two seeds, and partial containment where a read seed is absent
-// from the node genome.
 BOOST_AUTO_TEST_CASE(child_metrics_multiseed_hand_derived) {
     const uint64_t H1 = 0x1111, H2 = 0x2222;
     const double inv_sqrt2 = 1.0 / std::sqrt(2.0);
@@ -164,8 +150,7 @@ BOOST_AUTO_TEST_CASE(child_metrics_multiseed_hand_derived) {
     indexUtils::SeedCountMap rootGenome{{H1, 2}, {H2, 2}};
     auto state = makeState(readSeeds, rootGenome);
 
-    // (a) Node genome contains both seeds at count 2 (symmetric r=3,g=2 twice):
-    //     logRaw = (log4/2 + log4/2) / (log4·sqrt2) = 1/sqrt2; the other four scores = 1.
+    // (a) Both seeds in genome at count 2 (symmetric r=3,g=2): logRaw=1/sqrt2, other four scores=1.
     {
         std::vector<Change> ch = {{H1, 0, 2}, {H2, 0, 2}};
         placement::NodeMetrics m;
@@ -176,15 +161,11 @@ BOOST_AUTO_TEST_CASE(child_metrics_multiseed_hand_derived) {
         BOOST_CHECK_CLOSE(m.getWeightedContainmentScore(state.weightedContainmentDenominator), 1.0, 1e-3);
         BOOST_CHECK_CLOSE(m.getLogContainmentScore(state.logContainmentDenominator), 1.0, 1e-3);
         BOOST_CHECK_EQUAL(m.presenceIntersectionCount, 2u);
-        // The oracle must agree on the same state.
         auto oracle = indexUtils::GroundTruthMetrics::compute({{H1, 2}, {H2, 2}}, state);
         BOOST_CHECK_CLOSE(m.getLogRawScore(state.logReadMagnitude), oracle.logRawScore(state), 1e-3);
     }
 
-    // (b) Node genome contains only H1 (partial): H2 is a read seed missing from the
-    //     genome, so |reads∩genome|/|reads| = 1/2 and every read-interaction score halves:
-    //     logRaw = (log4/2)/(log4·sqrt2) = 1/(2·sqrt2); logCosine = log4·log3 /
-    //     (log4·sqrt2·log3) = 1/sqrt2; containment/weighted/logContainment = 1/2.
+    // (b) Genome has only H1; H2 read seed missing -> containment=1/2, read scores halve (logRaw=1/(2·sqrt2), logCosine=1/sqrt2).
     {
         std::vector<Change> ch = {{H1, 0, 2}};
         placement::NodeMetrics m;
@@ -198,14 +179,11 @@ BOOST_AUTO_TEST_CASE(child_metrics_multiseed_hand_derived) {
     }
 }
 
-// For nodes along the path to a known leaf, the five live getters must equal the oracle
-// computed from the reconstructed genome and the same state.
 BOOST_AUTO_TEST_CASE(all_metrics_equal_ground_truth_at_nodes) {
     const auto& fix = ts::sharedRSVFixture();
     const auto& d = ts::sharedRSVIndex();
     const auto& tree = *d.liteTree;
 
-    // Reads from the truth genome; seeds extracted the same way as the genome.
     std::string truthGenome = fix.genomeOf(kTruthNode);
     auto reads = ts::generateReads(truthGenome, 150, 200, 777);
     BOOST_REQUIRE(!reads.empty());
@@ -220,11 +198,9 @@ BOOST_AUTO_TEST_CASE(all_metrics_equal_ground_truth_at_nodes) {
     auto fullPath = ts::pathToRoot(tree, targetIdx);
     BOOST_REQUIRE(fullPath.size() >= 2);
 
-    // Root genome supplies the weighted-containment denominator.
     auto rootGenome = ts::reconstructGenomeSeeds({tree.root}, d);
     auto state = makeState(readSeeds, rootGenome);
 
-    // Check several nodes along the path (root, midpoint, leaf).
     std::vector<size_t> checkpoints = {1, fullPath.size() / 2, fullPath.size()};
     int comparisons = 0, nonTrivial = 0;
     for (size_t prefixLen : checkpoints) {
@@ -233,12 +209,11 @@ BOOST_AUTO_TEST_CASE(all_metrics_equal_ground_truth_at_nodes) {
         auto genome = ts::reconstructGenomeSeeds(prefix, d);
         auto oracle = indexUtils::GroundTruthMetrics::compute(genome, state);
 
-        // Genome-only: oracle and live agree on the genome magnitude.
         BOOST_CHECK_CLOSE(live.genomeMagnitudeSquared, oracle.genomeMagnitudeSquared, 1e-3);
         BOOST_CHECK_EQUAL(live.presenceIntersectionCount, oracle.presenceIntersectionCount);
 
-        // A ~0 oracle value only pins live ~0; count the nonzero comparisons so an
-        // all-zero degenerate run (no read/genome overlap) can't pass with trivial checks.
+        // A ~0 oracle value only pins live ~0; count nonzero comparisons so an all-zero
+        // degenerate run (no read/genome overlap) can't pass with trivial checks.
         auto closeOrZero = [&](double a, double b) {
             if (std::abs(b) < 1e-12) {
                 BOOST_CHECK_SMALL(a, 1e-9);
@@ -254,8 +229,7 @@ BOOST_AUTO_TEST_CASE(all_metrics_equal_ground_truth_at_nodes) {
                     oracle.weightedContainmentScore(state));
         closeOrZero(live.getLogContainmentScore(state.logContainmentDenominator), oracle.logContainmentScore(state));
 
-        // At the leaf (full path) the reads came from this genome, so containment must be
-        // substantial, not merely live == oracle.
+        // At the leaf, reads came from this genome, so containment must be substantial.
         if (prefixLen == fullPath.size()) {
             BOOST_TEST(oracle.containmentScore(state) > 0.5);
             BOOST_TEST(live.getContainmentScore(state.readUniqueSeedCount) > 0.5);
@@ -263,14 +237,9 @@ BOOST_AUTO_TEST_CASE(all_metrics_equal_ground_truth_at_nodes) {
         comparisons++;
     }
     BOOST_TEST(comparisons == 3);
-    // At least five comparisons must be against nonzero oracle values, not only ~0.
     BOOST_TEST(nonTrivial >= 5);
 }
 
-// Read-seed state construction: the min-read-support filter and the score denominators
-// (logReadMagnitude / logContainmentDenominator / readUniqueSeedCount) the getters divide
-// by, driven with hand-built seed frequencies and hand-derived expected values. makeState
-// only mimics this path.
 BOOST_AUTO_TEST_CASE(read_seed_state_and_min_support) {
     // resolveMinReadSupport auto-mode (configured = -1).
     {  // High coverage: three seeds seen in >=2 reads, mean count 4 > 3 -> require >=2.
@@ -298,8 +267,7 @@ BOOST_AUTO_TEST_CASE(read_seed_state_and_min_support) {
         BOOST_TEST(placement::resolveMinReadSupport(st.seedFreqInReads, 7) == 7);
     }
 
-    // computeReadSeedMagnitudes with minSupport=2 drops the singleton and builds the
-    // denominators over the surviving seeds only. Hand-derived from a:5, b:3, c:1.
+    // minSupport=2 drops the singleton; denominators over survivors only. Hand-derived from a:5, b:3, c:1.
     {
         placement::PlacementGlobalState st;
         st.seedFreqInReads[0xA1] = 5;
@@ -309,8 +277,8 @@ BOOST_AUTO_TEST_CASE(read_seed_state_and_min_support) {
         const size_t filtered = placement::computeReadSeedMagnitudes(st, 2);
         const double la = std::log1p(5.0), lb = std::log1p(3.0);
 
-        BOOST_TEST(filtered == 1u);                  // c (count 1 < 2) dropped
-        BOOST_TEST(st.readUniqueSeedCount == 2u);    // a, b kept
+        BOOST_TEST(filtered == 1u);
+        BOOST_TEST(st.readUniqueSeedCount == 2u);
         BOOST_TEST(st.totalReadSeedFrequency == 9);  // 5+3+1, counted before the filter
         BOOST_TEST(st.logReadCounts.size() == 2u);
         BOOST_TEST(st.logReadCounts.count(0xC3) == 0u);
diff --git a/src/test/test_seeding.cpp b/src/test/test_seeding.cpp
index 0a76db89..e2ba288f 100644
--- a/src/test/test_seeding.cpp
+++ b/src/test/test_seeding.cpp
@@ -49,9 +49,8 @@ BOOST_AUTO_TEST_CASE(rollingsyncmers_contract) {
                 for (size_t i = 0; i < all.size(); ++i) {
                     BOOST_TEST(std::get<0>(all[i]) == std::get<0>(all2[i]));
                 }
-                // Non-sentinel entries store the canonical (orientation-invariant)
-                // k-mer hash; returnAll=true yields UINT64_MAX sentinels at
-                // non-syncmer positions.
+                // Non-sentinel entries store the canonical k-mer hash; returnAll=true yields
+                // UINT64_MAX sentinels at non-syncmer positions.
                 for (const auto& [hash, isRev, isSync, pos] : all) {
                     BOOST_REQUIRE(pos >= 0);
                     BOOST_REQUIRE(static_cast<size_t>(pos) + k <= seq.size());
diff --git a/src/zstd_compression.cpp b/src/zstd_compression.cpp
index 413116a6..d367a4c3 100644
--- a/src/zstd_compression.cpp
+++ b/src/zstd_compression.cpp
@@ -27,8 +27,7 @@ bool compressToFile(const void* inputData,
         frameSize = 64ull * 1024 * 1024;
     }
 
-    // Independent per-chunk frames (not one nbWorkers frame) so decompressFromFile
-    // can inflate them in parallel -- single-frame inflate dominates large-index load.
+    // Independent per-chunk frames so decompressFromFile can inflate them in parallel.
     const size_t numChunks = std::max<size_t>(1, (inputSize + frameSize - 1) / frameSize);
 
     logging::info("Compressing {} bytes to {} with ZSTD level {} using {} threads ({} frames x {} MB)",
@@ -56,7 +55,7 @@ bool compressToFile(const void* inputData,
             return;
         }
         ZSTD_CCtx_setParameter(cctx, ZSTD_c_compressionLevel, compressionLevel);
-        ZSTD_CCtx_setParameter(cctx, ZSTD_c_checksumFlag, 1);  // one-shot => content-size header written
+        ZSTD_CCtx_setParameter(cctx, ZSTD_c_checksumFlag, 1);
         const size_t r = ZSTD_compress2(cctx, out.data(), out.size(), in + inOff, inLen);
         ZSTD_freeCCtx(cctx);
         if (ZSTD_isError(r)) {
@@ -65,7 +64,7 @@ bool compressToFile(const void* inputData,
             return;
         }
         out.resize(r);
-        out.shrink_to_fit();  // free the compressBound slack so only ~compressed size is held
+        out.shrink_to_fit();
         frames[i] = std::move(out);
     });
 
@@ -78,11 +77,11 @@ bool compressToFile(const void* inputData,
         logging::err("Failed to open output file: {}", outputPath);
         return false;
     }
-    if (headerData != nullptr && headerSize > 0) {  // uncompressed prefix (e.g. index params)
+    if (headerData != nullptr && headerSize > 0) {
         outFile.write(reinterpret_cast<const char*>(headerData), static_cast<std::streamsize>(headerSize));
     }
     size_t compressedSize = 0;
-    for (const auto& f : frames) {  // concatenate frames in order
+    for (const auto& f : frames) {
         outFile.write(reinterpret_cast<const char*>(f.data()), static_cast<std::streamsize>(f.size()));
         if (!outFile) {
             logging::err("Failed to write compressed data to file: {}", outputPath);
@@ -134,11 +133,10 @@ bool decompressFromFile(const std::string& inputPath, std::vector<uint8_t>& outp
     const char* compressedData = mappedFile.data();
     size_t compressedSize = mappedFile.size();
 
-    // Total size = sum over frames; getFrameContentSize on the whole buffer reports
-    // only the first frame (indexes are written multi-frame).
+    // getFrameContentSize reports only the first frame; sum over all frames.
     size_t numFrames = 0;
     unsigned long long decompressedSize = 0;
-    size_t pos = dataOffset;  // skip an uncompressed header prefix, if any
+    size_t pos = dataOffset;
     while (pos < compressedSize) {
         unsigned long long frameCompSize = ZSTD_findFrameCompressedSize(compressedData + pos, compressedSize - pos);
         if (ZSTD_isError(frameCompSize)) {
@@ -170,7 +168,7 @@ bool decompressFromFile(const std::string& inputPath, std::vector<uint8_t>& outp
         std::vector<std::pair<size_t, size_t>> frameRanges;
         std::vector<std::pair<size_t, size_t>> outputRanges;
 
-        pos = dataOffset;  // frames begin after the uncompressed header
+        pos = dataOffset;
         size_t outPos = 0;
         while (pos < compressedSize) {
             unsigned long long frameCompSize = ZSTD_findFrameCompressedSize(compressedData + pos, compressedSize - pos);
@@ -224,8 +222,7 @@ bool decompressFromFile(const std::string& inputPath, std::vector<uint8_t>& outp
             return false;
         }
 
-        // ZSTD_decompressDCtx handles one frame; walk them for multi-frame input.
-        size_t inPos = dataOffset;  // frames begin after the uncompressed header
+        size_t inPos = dataOffset;
         size_t outPos = 0;
         while (inPos < compressedSize) {
             unsigned long long frameCompSize =
diff --git a/src/zstd_compression.hpp b/src/zstd_compression.hpp
index b972c03c..cc4d009c 100644
--- a/src/zstd_compression.hpp
+++ b/src/zstd_compression.hpp
@@ -7,26 +7,18 @@
 
 namespace panmap_zstd {
 
-/**
- * Compress inputData to outputPath with parallel ZSTD.
- * compressionLevel: 1-22. numThreads: 0 = auto-detect. frameSize: seekable
- * frame size in bytes. Returns true on success.
- */
+// numThreads 0 = auto-detect; compressionLevel 1-22.
 [[nodiscard]] bool compressToFile(const void* inputData,
                                   size_t inputSize,
                                   const std::string& outputPath,
                                   int compressionLevel = 3,
                                   int numThreads = 0,
-                                  size_t frameSize = 4 * 1024 * 1024,  // 4MB frames
-                                  const void* headerData = nullptr,    // optional uncompressed prefix,
-                                  size_t headerSize = 0                // written verbatim before the frames
+                                  size_t frameSize = 4 * 1024 * 1024,
+                                  const void* headerData = nullptr,    // uncompressed prefix, written verbatim before the frames
+                                  size_t headerSize = 0
 );
 
-/**
- * Decompress inputPath into outputData (resized to fit) with parallel ZSTD.
- * numThreads: 0 = auto-detect. dataOffset: skip this many leading bytes (an
- * uncompressed header) before the ZSTD frames. Returns true on success.
- */
+// numThreads 0 = auto-detect; dataOffset skips a leading uncompressed header.
 [[nodiscard]] bool
 decompressFromFile(const std::string& inputPath, std::vector<uint8_t>& outputData, int numThreads = 0,
                    size_t dataOffset = 0);