From 5c9cb9bcd50459aa8398ed9f643bf389219c6a5d Mon Sep 17 00:00:00 2001
From: b_Jimmy <b_jimmy@gitea.local>
Date: Mon, 7 Sep 2026 17:45:46 +0000
Subject: [PATCH] add .agents/skills/storyline/SKILL.md

---
 .agents/skills/storyline/SKILL.md | 36 +++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 .agents/skills/storyline/SKILL.md

diff --git a/.agents/skills/storyline/SKILL.md b/.agents/skills/storyline/SKILL.md
new file mode 100644
index 0000000..93e90a6
--- /dev/null
+++ b/.agents/skills/storyline/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: storyline
+description: News-aggregator story layer workflow. Use when working on cluster.py, the
+  prototype story engine, or the dsh backlog for it.
+runtime: python
+---
+
+# Storyline skill — FreshRSS-adjacent story layer
+
+The repo is a **thin story layer beside a stock FreshRSS container**. Read AGENTS.md
+before any change; its rules are binding (keep tests green, no FreshRSS rebuild,
+no Kafka, no frontend framework, capped LLM, Hermes at :8080, fixed ports).
+
+## Mental model
+`sources → fetch → dedup → cluster → rank → [LLM top-k] → out/index.html`
+
+- **Dedup**: pass 1 exact (normalized title / canonical URL), pass 2 MinHash-LSH →
+  connected-component clusters (transitive merge).
+- **Rank**: `score = authority * (coverage_count + 1) / (age_h + 2)^1.8`.
+  coverage_count (# sources on a story) is the "importance" signal — no votes.
+- **LLM**: only top-k (default 10) get summarized; input = headline + ~300 chars.
+- **Ports**: FreshRSS 8280, RSSHub 1200, Hermes 8080, `--serve` 8765.
+
+## Verify every change
+```bash
+cd prototype && python -m pytest -q
+```
+Acceptance is "two reworded copies → one cluster" (see `test_cluster.py`).
+
+## Typical runs
+```bash
+python cluster.py --snapshot fr-export.json --llm --topk 10   # from FreshRSS export
+python cluster.py --opml feeds.opml --llm --serve :8765       # live HTTP feeds, dev
+LLM_BASE_URL=http://127.0.0.1:8080/v1 LLM_MODEL=hermes python cluster.py --llm
+```
+Never point summaries at DeepSeek unless the operator changes `LLM_BASE_URL` on purpose.
\ No newline at end of file