chore: neutral report path and plain punctuation

The markdown report wrote to a directory named after the tooling that
happened to produce it. It takes --report-dir now, defaulting to
reports/, so nothing in the tree names anything but the project.

Em-dashes replaced throughout the sources and tests, rephrased rather
than swapped for a comma where the dash carried an apposition.

scripts/common.py

@@ -171,7 +171,7 @@ def load_platform_config(platform_name: str, platforms_dir: str = "platforms") -
                 config["cores"] = reg_cores
 
         # Merge all registry fields absent from config (except cores,
-        # handled above with union logic). No hardcoded list — any field
+        # handled above with union logic). No hardcoded list: any field
         # added to the registry is automatically available in the config.
         for key, val in reg_entry.items():
             if key != "cores" and key not in config:

scripts/generate_pack.py

@@ -974,7 +974,7 @@ def generate_pack(
           # Core extras: _collect_emulator_extras already adjusted
           # destinations for slug-based platforms.  Apply the effective
           # prefix (base_dest, or inferred from YAML when base_dest is
-          # empty — e.g. RetroDECK infers "bios").
+          # empty, as RetroDECK infers "bios").
           extras_pfx = _detect_extras_prefix(config, base_dest)
           if extras_pfx:
               if not dest.startswith(f"{extras_pfx}/"):

scripts/packextras.py

@@ -148,7 +148,7 @@ def _agnostic_scan_extras(
     """
     extras: list[dict] = []
     files_db = db.get("files", {})
-    # Third pass: agnostic scan — for filename-agnostic cores, include all
+    # Third pass: the agnostic scan. For filename-agnostic cores, include all
     # DB files matching the system path prefix and size criteria.
     for emu_name, profile in sorted(profiles.items()):
         if profile.get("type") in ("launcher", "alias"):

scripts/profile_sync.py

@@ -2298,6 +2298,11 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--changed-only", action="store_true")
     parser.add_argument("--json", action="store_true", dest="as_json")
     parser.add_argument("--markdown", action="store_true")
+    parser.add_argument(
+        "--report-dir",
+        default="reports",
+        help="directory for the markdown report (default: reports)",
+    )
     parser.add_argument("--fetch-plan", action="store_true")
     parser.add_argument("--full-diff", action="store_true")
     parser.add_argument("--ref", help="restrict --full-diff to one cited path")
@@ -2617,7 +2622,7 @@ def main() -> None:
         print(json.dumps([report_to_dict(r) for r in reports], indent=2))
         return
     if args.markdown:
-        target = Path("claudedocs") / f"profile-sync-{date.today().isoformat()}.md"
+        target = Path(args.report_dir) / f"profile-sync-{date.today().isoformat()}.md"
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(format_markdown(reports), encoding="utf-8")
         print(f"written: {target}")

scripts/truth.py

@@ -49,7 +49,7 @@ def _enrich_hashes(entry: dict, db: dict) -> None:
 
     The profile's hashes come from the emulator source code (ground truth).
     Any hash of a given file set of bytes is a projection of that same
-    ground truth — sha1, md5, crc32 all identify the same bytes. If the
+    ground truth. sha1, md5 and crc32 all identify the same bytes. If the
     profile has ONE ground-truth hash, the DB can supply its siblings.
 
     Lookup order (all are hash-anchored, never name-based):
@@ -64,7 +64,7 @@ def _enrich_hashes(entry: dict, db: dict) -> None:
     Multi-hash entries (lists of accepted variants) are left untouched to
     preserve variant information.
     """
-    # Skip multi-hash entries — they express ground truth as "any of these N
+    # Skip multi-hash entries. They express ground truth as "any of these N
     # variants", enriching with a single sibling would lose that information.
     for h in ("sha1", "md5", "crc32"):
         if isinstance(entry.get(h), list):
@@ -388,7 +388,7 @@ def generate_platform_truth(
 
     # Drop files with no exploitable data AFTER all cores have contributed.
     # A file declared by one core without hash/size/path may be enriched by
-    # another core that has the same entry with data — the filter must run
+    # another core that has the same entry with data, so the filter must run
     # once at the end, not per-core at creation time.
     for sys_data in systems.values():
         files_list = sys_data.get("files", [])
@@ -437,7 +437,7 @@ def _match_renames(
     """
     # Hash-based fallback: detect platform renames (e.g. Batocera ROM → ROM1)
     # If an unmatched scraped file shares a hash with an unmatched truth file,
-    # it's the same file under a different name — a platform rename, not a gap.
+    # it's the same file under a different name: a platform rename, not a gap.
     rename_matched_truth: set[str] = set()
     rename_matched_scraped: set[str] = set()
 
@@ -457,7 +457,7 @@ def _match_renames(
                     continue
                 t_entry = truth_hash_index.get(s_val.lower())
                 if t_entry is not None:
-                    # Rename detected — count as matched
+                    # Rename detected. Count as matched
                     rename_matched_truth.add(t_entry["name"].lower())
                     rename_matched_scraped.add(s_key)
                     break

scripts/verify.py

@@ -678,15 +678,15 @@ def _find_best_variant(
     """Search for a repo file that passes emulator validation.
 
     Two-pass search:
-    1. Hash lookup — use the emulator's expected hashes (sha1, md5, sha256,
+    1. Hash lookup, using the emulator's expected hashes (sha1, md5, sha256,
        crc32) to find candidates directly in the DB indexes.  This finds
        variants stored under different filenames (e.g. megacd2_v200_eu.bin
        for bios_CD_E.bin).
-    2. Name lookup — check all files sharing the same name (aliases,
+    2. Name lookup, checking all files sharing the same name (aliases,
        .variants/ with name-based suffixes).
 
     If any candidate on disk passes ``check_file_validation``, the
-    discrepancy is suppressed — the repo has what the emulator needs.
+    discrepancy is suppressed: the repo has what the emulator needs.
     """
     fname = file_entry.get("name", "")
     if not fname or fname not in validation_index:

tests/test_e2e.py

@@ -700,7 +700,7 @@ class TestE2E(unittest.TestCase):
             yaml.dump(emu_subdir, fh)
 
         # Emulator whose file is declared by platform under a different name
-        # (e.g. gsplus ROM vs Batocera ROM1) — hash-based matching should resolve
+        # (e.g. gsplus ROM vs Batocera ROM1): hash-based matching should resolve
         emu_renamed = {
             "emulator": "TestRenamed",
             "type": "standalone",
@@ -712,7 +712,7 @@ class TestE2E(unittest.TestCase):
         with open(os.path.join(self.emulators_dir, "test_renamed.yml"), "w") as fh:
             yaml.dump(emu_renamed, fh)
 
-        # Agnostic profile (bios_mode: agnostic) — skipped by find_undeclared_files
+        # Agnostic profile (bios_mode: agnostic), skipped by find_undeclared_files
         emu_agnostic = {
             "emulator": "TestAgnostic",
             "type": "standalone",
@@ -4278,7 +4278,7 @@ class TestE2E(unittest.TestCase):
         }
 
         result = diff_platform_truth(truth, scraped)
-        # ROM and ROM1 share the same hash — rename, not missing+phantom
+        # ROM and ROM1 share the same hash: a rename, not missing plus phantom
         self.assertEqual(result["summary"]["total_missing"], 0)
         self.assertEqual(result["summary"]["total_extra_phantom"], 0)