From 660f03674bcf7c5483ff8b5223d302021f39cb24 Mon Sep 17 00:00:00 2001
From: root <root@localhost.localdomain>
Date: Tue, 31 Mar 2026 15:55:15 +0800
Subject: [PATCH] docs: align reader docs with digest SOP defaults

---
 README.md                         | 12 +++++++++++-
 docs/openclaw/openclaw-handoff.md |  8 ++++----
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 696d317..21fb033 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,13 @@ The server exposes five tools:
 
 Article-summary post-processing (separate LLM optional):
 
+**Recommended production input for selected-article summaries**
+
+- Use the per-item extracted files written by the main FreshRSS pipeline:
+  - `outputs/freshrss/rerun/<run_id>/extracted/item-XX.extracted.json`
+- Treat these per-item extracted files as the formal default artifacts for downstream selected-article summarization.
+- A batch extracted file such as `outputs/freshrss/extracted/freshrss.extracted.json` is only a compatible input shape for ad hoc or legacy workflows, not the preferred production default.
+
 Daily knowledge-base defaults:
 
 - `IMA_DAILY_KNOWLEDGE_BASE_ID` — default IMA knowledge base ID for daily single-article summaries
@@ -77,6 +84,8 @@ The script writes:
 - `outputs/freshrss/items/freshrss.items.json`
 - `outputs/freshrss/extracted/freshrss.extracted.json`
 
+Note: this batch extracted file is mainly a compatible artifact for standalone extraction runs and older workflows. The formal production default for downstream selected-article summarization is still the per-item extracted output under `outputs/freshrss/rerun/<run_id>/extracted/item-XX.extracted.json`.
+
 Run the full FreshRSS pipeline and mark items as read only after the final OpenClaw delivery payload is written:
 
 ```bash
@@ -248,7 +257,8 @@ set ARTICLE_SUMMARY_LLM_API_KEY=your-article-summary-key
 set ARTICLE_SUMMARY_LLM_MODEL=deepseek-chat
 ```
 
-Then run, for example, either via the CLI script:
+Then run, for example, either via the CLI script.
+For normal production use, prefer a per-item extracted file from `outputs/freshrss/rerun/<run_id>/extracted/`. The batch extracted example below is kept only as a compatible legacy/ad hoc input shape:
 
 ```bash
 python scripts/run_article_summaries.py ^
diff --git a/docs/openclaw/openclaw-handoff.md b/docs/openclaw/openclaw-handoff.md
index d06ca4a..0aacb3a 100644
--- a/docs/openclaw/openclaw-handoff.md
+++ b/docs/openclaw/openclaw-handoff.md
@@ -54,12 +54,12 @@ summary-mcp
 
 ## Recommended MCP Call
 
-Recommended default call:
+Recommended production call:
 
 ```json
 {
   "limit": 5,
-  "mark_read": false,
+  "mark_read": true,
   "include_read": false,
   "debug_artifacts": false,
   "timeout_seconds": 60,
@@ -69,8 +69,8 @@ Recommended default call:
 
 Recommended semantics:
 
-- Use `mark_read=false` while validating integration.
-- Use `mark_read=true` only after confirming OpenClaw will consume the returned payload successfully.
+- Use `mark_read=true` for normal production runs.
+- Use `mark_read=false` only for debug, test, or validation runs.
 - Keep `debug_artifacts=false` for routine production runs.
 - Set `debug_artifacts=true` only when troubleshooting a bad batch.