Simplify scan results with readable summary and matched-event CSV

README.md

@@ -57,21 +57,35 @@ directories; review the preparation manifest for unusual export layouts.
 
 ## Read the results
 
+Start with these three files:
+
+```text
+triage-results-.../
+  SUMMARY.txt       Start here
+  FINDINGS.csv      Review matched events
+  IOCS.csv          Search candidates for your SIEM
+  details/         Full evidence and machine-readable exports
+  inputs/          Prepared input copies, when preparation was needed
+```
+
 | File | Purpose |
 | --- | --- |
-| `summary.json` | Processing status, counts and incomplete coverage |
-| `findings.jsonl` | Events, source lines, matching rules and decoding explanations |
-| `IOCS.csv` | Exact SIEM search values and separate defanged display values |
-| `updates.jsonl` | Installation and software-version evidence |
-| `correlations.jsonl` | Related events on the same appliance; temporal candidates, not causal proof |
-| `coverage.json` | Per-file coverage and errors |
-| `input_manifest.json` | Original relative paths and SHA-256 checksums |
-| `preparation_manifest.json` | Archive preparation and appliance grouping |
+| `SUMMARY.txt` | Readable overview: coverage, counts, limitations and what to open next |
+| `FINDINGS.csv` | Only rule/indicator matches, with explanations and original source references |
+| `IOCS.csv` | SIEM search candidates; not an automatic blocklist |
 
-The output also includes an SQLite event index, effective configuration and
-indicator/hash hit files. JSONL contains one JSON object per line. URL/Base64
-decoding retains original values, transformation steps, checksums and errors.
-An installer command alone does not establish successful patch completion.
+All technical exports are under `details/`: full events in `findings.jsonl`,
+URL/Base64 decoding, updates, correlations, checksums, coverage and the SQLite
+index. Prepared input copies, if needed, remain in `inputs/`.
+
+`details/findings.jsonl` includes context and processing errors as well as matches;
+use `FINDINGS.csv` to browse matched events. A match is not proof of execution.
+The CSV keeps authorized-test and reference statuses visible. Spreadsheet-sensitive
+cells are prefixed with an apostrophe; exact original values remain in JSON.
+
+This layout applies to CLI scans. Direct Python calls to `engine.scan` retain
+flat machine-readable exports. Failed or interrupted scans can also retain the
+flat layout; inspect their `summary.json` before using partial results.
 
 ## Add indicators and Sigma rules
 
@@ -112,7 +126,9 @@ repository. Examples under [examples/](examples/) use synthetic data.
 ## Limits and interpretation
 
 - Exit `0`: configured processing completed; **not** a clean-system verdict.
-- Exit `2`: an error or incomplete processing; inspect `summary.json`.
+- Exit `2`: an error or incomplete processing; inspect `SUMMARY.txt` and
+  `details/summary.json`. If the scan failed before presentation, inspect
+  `summary.json` at the result root instead.
 - Missing years/timezones are not guessed. See [README.txt](README.txt) for time configuration.
 - Binary appliance logs may need an external decoder. Decode failures can also come from ordinary text.
 - Damaged inputs and regex timeouts are reported. Archive path traversal, unsafe links and exhausted quotas stop preparation.