1 files changed, 55 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a8e8ec1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# fluxrec
+
+Personal Miniflux article recommender. Ranks your incoming RSS entries with a
+title-only classifier trained on the ones you star, and serves the top picks
+as an RSS feed you subscribe to in Miniflux itself. Read-only toward Miniflux.
+No deps beyond stdlib + vendored ML core.
+
+## Requirements
+
+- Miniflux ≥ 2.0.49 (uses the `changed_after`/`published_after` entry filters)
+- Go ≥ 1.25 to build; everything else is stdlib + the vendored core in `core/`
+- Training runs wherever you read (`export`/`train`); `serve` runs next to
+  Miniflux and only needs the model file
+
+## Commands
+
+```
+fluxrec export     stars + sampled negatives → labels.jsonl   (local)
+fluxrec train      labels.jsonl → model.json + report.json    (local)
+fluxrec serve      poll, score, RSS at /recommendations.xml   (server)
+fluxrec retrostar  model-ranked candidates to star by hand    (cold start)
+fluxrec score      debug: stdin titles → stdout scores
+```
+
+## Setup
+
+```
+just auth           # prints the two export lines; paste them in your shell
+# one-time: retroactively star 50–100 remembered-good entries in Miniflux
+# then weekly-ish:
+just retrain          # export + train; read report.json (precision@15)
+just ship myhost      # scp model.json + restart serve (myhost = ssh alias)
+# finally: subscribe your Miniflux to https://server/recommendations.xml
+```
+
+Deploy serve only after a real model exists with an honest precision@15.
+
+## Files
+
+```
+labels.jsonl       canonical label store (survives Miniflux deletion)
+export_state.json  local incremental cursor
+export_run.json    per-run summary (overwritten each export)
+model.json         TF-IDF vocab + LR weights (trained locally, shipped to server)
+report.json        train's validation report (precision@15 headline metric)
+cursor.json        server poll cursor
+runs.jsonl         server run log; doubles as the RSS render source
+```
+
+## Notes
+
+- Never writes to Miniflux. Never needs credentials in the repo.
+- Training stays on the local PC; the server only scores (low RAM).
+- Deploy `serve` only after a `train` run on enough organic stars shows an
+  honest precision@15 in report.json; tiny validation sets lie.