From 1bbb6e5bce56e721ab685af4cd87df21bbff4d35 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Tue, 25 Aug 2026 04:00:37 -0700
Subject: [PATCH] =?UTF-8?q?docs(skill):=20troubleshoot=20stale=20web=5Fext?=
 =?UTF-8?q?ract=20pages=20=E2=80=94=20cache=20carveouts=20+=20cache=5Fexem?=
 =?UTF-8?q?pt=5Fhosts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a 'web_extract shows a stale page' section to the bundled
hermes-agent skill's troubleshooting reference: the 20-minute TTL
symptom, the automatic never-cache carveouts (localhost/private/LAN,
website_blocklist, rescue/failed responses), the web.cache_exempt_hosts
recipe for staging/tunnel sites, and the TTL/disable fallbacks.
---
 .../references/troubleshooting.md             | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md b/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md
index aedf0e219f..dc13f0fb1e 100644
--- a/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md
@@ -21,6 +21,33 @@
 - **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
 - **Code changes:** Restart the CLI or gateway process
 
+### web_extract shows a stale page (result caching)
+`web_search`/`web_extract` cache results for 20 minutes (PR #94618) — a
+repeat fetch of the same URL within the TTL is served from cache, which
+can look like "my website changes aren't showing up."
+
+Automatic carveouts (always fetched live, never cached):
+- localhost / 127.0.0.1 / `*.local` / `*.localhost` / single-label LAN
+  hostnames / private + link-local IP ranges (dev servers, hot-reload
+  builds, chat-GUI artifact previews)
+- URLs matched by `security.website_blocklist`
+- failed responses and keyless-rescue-served responses
+
+Developing a site tested over the PUBLIC internet (Vercel/Netlify
+preview, ngrok/cloudflared tunnel, staging domain)? Public DNS isn't
+auto-carved-out — list the host in config.yaml:
+
+```yaml
+web:
+  cache_exempt_hosts:      # always fetched live; effective immediately
+    - mysite.vercel.app
+    - "*.ngrok-free.app"
+    - mysite.dev           # suffix match: also covers preview.mysite.dev
+```
+
+Blunt instruments: `web.cache_ttl_minutes: 1` (min) or
+`web.cache_enabled: false` disables both caches entirely.
+
 ### Skills not showing
 1. `hermes skills list` — verify installed
 2. `hermes skills config` — check platform enablement