From f8a04739c0d042a4aece68d781b9de5520c130dc Mon Sep 17 00:00:00 2001
From: sid-plt <218677312+sid-plt@users.noreply.github.com>
Date: Sun, 23 Aug 2026 17:45:40 +0200
Subject: [PATCH] Document output retention policy

---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index c834b52..35bf146 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,21 @@ player data from SofaScore, FotMob, Transfermarkt, KBStats, and Analyst.
 Generated JSON, CSV, and debug HTML must be written through `project_paths.py`;
 do not write generated files beside a notebook or into the project root.
 
+## Timestamped output retention
+
+Timestamped output exporters invoke the shared cleanup in `project_paths.py`. The
+cleanup uses the final timestamp in a filename as the output creation time and
+retains the 10 newest files in each applicable family. Files without a supported
+creation timestamp in their filename are never removed.
+
+Most families are distinguished by output directory, filename pattern with
+timestamps removed, and file extension. Meaningful labels such as matchday,
+percentile, and datatype remain separate. Two high-volume CSV directories use a
+single limit across their methods: `outputs/expected_points` retains its 10 newest
+expected-points CSVs, and `outputs/optimized_squad` retains its 10 newest optimizer
+CSVs. Run timestamped-output notebooks through their final retention cell to apply
+the same cleanup after notebook exports.
+
 ## Setup
 
 From PowerShell in the project root: