From bc165093e2661245f775b64064d9b86fcb5f3c1e Mon Sep 17 00:00:00 2001
From: Ben_Kosytorz <benkosytorz@mail.me>
Date: Sun, 11 Oct 2026 12:55:30 +0200
Subject: [PATCH] docs: record the sorter's default (non-provenance) mode

- docs/SORTING.md: the extraction section now shows the default sort command (no --provenance) and presents --provenance as an optional mode.
- AGENTS.md 7: note that sorting runs in the default mode and that mixing the two modes creates duplicate placements.
Docs-only change; no code touched.
---
 AGENTS.md       |  5 +++++
 docs/SORTING.md | 15 ++++++++++-----
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 159d336..0987529 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -230,6 +230,11 @@ sorting pipeline — **change it first, then the code**. Summary:
   candidates). Weak hits ≥ `WEAK_MIN = 0.50` are accepted but flagged
   low-confidence. Tokenless normal adoption needs `+0.08`
   (`TOKENLESS_BONUS`).
+- Sorting runs in the sorter's **default (non-provenance) mode**: every
+  file is classified on its own name (unclassified files land directly in
+  `_unsorted/<file>`). `--provenance` (classify whole extraction dirs as
+  units) exists but the live library does **not** use it; mixing the two
+  modes creates duplicate placements.
 - `DROPPED_SYSTEMS` (default `{Middle-Earth}`) filters catalog entries at load
   and counts keyword hits as unclassified; `--drop-system`/`--keep-system`
   adjust. The committed catalog snapshot keeps all systems.
diff --git a/docs/SORTING.md b/docs/SORTING.md
index 7e9523c..f759bbe 100644
--- a/docs/SORTING.md
+++ b/docs/SORTING.md
@@ -119,12 +119,17 @@ plan/apply-only):
   password archives, disk full) are moved to `<out>/.broken/` and the run
   continues; re-runs skip already-extracted destinations.
 - `<out>/extract_manifest.jsonl` records `{archive, dest, unit}` per
-  extraction. The sorter's `--provenance` flag reads it: all files inside
-  an extraction directory are classified **once under the archive's
-  name** (a loose `Backpack.stl` alone is noise; under
-  `The Twin Lance/` it belongs to that unit) and placed together, keeping
-  the archive's inner directory structure:
+  extraction. By **default the sorter classifies each file on its own
+  name**; the optional `--provenance <manifest>` mode instead classifies
+  each extraction directory **once under the archive's name** (a loose
+  `Backpack.stl` alone is noise; under `The Twin Lance/` it belongs to
+  that unit) and keeps the archive's inner directory structure. The live
+  library uses the default (non-provenance) mode:
 
+      # default — what Warhammer_Library_Live uses
+      dlphelper sorter <extracted_root> --library <lib> --apply
+
+      # optional provenance mode (whole extraction dirs as units)
       dlphelper sorter <extracted_root> --library <lib> \
           --provenance <extracted_root>/extract_manifest.jsonl --apply