From 85f108ef039c601c283f9558cd28a97271339ce5 Mon Sep 17 00:00:00 2001
From: loes5050 <88768844+loes5050@users.noreply.github.com>
Date: Sat, 20 Jun 2026 19:16:13 +0400
Subject: [PATCH] test(cron): document consent-first self-learning suggestions

---
 tests/cron/test_suggestions.py             | 16 ++++++++++++++++
 website/docs/user-guide/features/memory.md |  8 ++++++--
 website/docs/user-guide/features/skills.md |  6 ++++++
 3 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/tests/cron/test_suggestions.py b/tests/cron/test_suggestions.py
index 75ee7fe7a87..710c5ea93ff 100644
--- a/tests/cron/test_suggestions.py
+++ b/tests/cron/test_suggestions.py
@@ -62,6 +62,22 @@ class TestStore:
         with pytest.raises(ValueError):
             store.add_suggestion(title="x", description="d", source="bogus", job_spec={}, dedup_key="k")
 
+    def test_usage_source_is_consent_first_self_improvement(self, store):
+        """Background review suggestions must stay pending until user acceptance."""
+        rec = _add(
+            store,
+            key="usage:weekly-summary",
+            title="Weekly project summary",
+            source="usage",
+            schedule="0 17 * * 5",
+        )
+
+        assert rec is not None
+        assert rec["source"] == "usage"
+        assert rec["status"] == "pending"
+        assert rec["job_spec"]["schedule"] == "0 17 * * 5"
+        assert store.list_pending()[0]["dedup_key"] == "usage:weekly-summary"
+
     def test_pending_cap(self, store):
         for i in range(store.MAX_PENDING):
             assert _add(store, key=f"k{i}") is not None
diff --git a/website/docs/user-guide/features/memory.md b/website/docs/user-guide/features/memory.md
index 91874c73e01..41efc92285c 100644
--- a/website/docs/user-guide/features/memory.md
+++ b/website/docs/user-guide/features/memory.md
@@ -248,8 +248,12 @@ ones — waits for your yes/no before it ever enters your profile.
 ## Background review notifications (`display.memory_notifications`)
 
 After a turn, the background self-improvement review may quietly save a memory
-or update a skill. By default it surfaces a short `💾 Memory updated` line in
-chat so you know it happened. Control how chatty that is:
+or update a skill. This is Hermes' consent-aware learning loop: repeated
+corrections and durable workflow lessons become compact memory entries or
+procedural skills, while `write_approval` can stage those writes for review
+before they affect future sessions. By default it surfaces a short
+`💾 Memory updated` line in chat so you know it happened. Control how chatty
+that is:
 
 ```yaml
 display:
diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md
index 6cfbafee3c3..c562c5fc9c9 100644
--- a/website/docs/user-guide/features/skills.md
+++ b/website/docs/user-guide/features/skills.md
@@ -379,6 +379,12 @@ A bundle is just a YAML alias — it doesn't install skills for you. The skills
 
 The agent can create, update, and delete its own skills via the `skill_manage` tool. This is the agent's **procedural memory** — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.
 
+Skills and memory work together in the self-improvement loop: memory stores
+small durable facts that should always be in context, while skills store longer
+procedures that should load only when relevant. The background review can
+suggest or stage skill changes after a session, but the write-approval gate
+below lets you require human review before those changes land.
+
 ### When the Agent Creates Skills
 
 - After completing a complex task (5+ tool calls) successfully