better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md

@@ -1,326 +0,0 @@
----
-title: "Pinggy Tunnel — Zero-install localhost tunnels over SSH via Pinggy"
-sidebar_label: "Pinggy Tunnel"
-description: "Zero-install localhost tunnels over SSH via Pinggy"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Pinggy Tunnel
-
-Zero-install localhost tunnels over SSH via Pinggy.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/devops/pinggy-tunnel` |
-| Path | `optional-skills/devops\pinggy-tunnel` |
-| Version | `0.1.0` |
-| Author | Teknium (teknium1), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Pinggy`, `Tunnel`, `Networking`, `SSH`, `Webhook`, `Localhost` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Pinggy Tunnel Skill
-
-Expose a local service (dev server, webhook receiver, MCP endpoint, demo) to the public internet using a Pinggy SSH reverse tunnel. No daemon to install — the user's stock SSH client connects to `a.pinggy.io:443` and Pinggy hands back a public HTTP/HTTPS URL.
-
-Free tier: 60-minute tunnels, random subdomain, no signup. Pro tier ($3/mo) is an opt-in with a token.
-
-## When to Use
-
-- User asks to "expose this locally", "share my dev server", "make this URL public", "tunnel port N", "get a public URL for a webhook"
-- Need to receive a webhook callback during a local task (Stripe, GitHub, Discord, AgentMail)
-- Sharing a one-off HTTP demo (MCP server, Ollama/vLLM endpoint, dashboard) with a remote party
-- The host has SSH but no `cloudflared` / `ngrok` binary, and installing one would be overkill
-
-If the host already has `cloudflared` configured, prefer the `cloudflared-quick-tunnel` skill — Cloudflare quick tunnels don't expire after 60 minutes.
-
-## Prerequisites
-
-- `ssh` on PATH (`ssh -V`). Default on Linux, macOS, and Windows 10+. No other install.
-- A local service listening on `127.0.0.1:<port>` before the tunnel starts. Pinggy will return URLs but they'll 502 until the local origin is up.
-
-Optional:
-
-- `PINGGY_TOKEN` env var for paid Pro features (persistent subdomain, custom domain, multiple tunnels, no 60-minute cap). Free tier needs no credentials.
-
-## Quick Reference
-
-```bash
-# Plain HTTP/HTTPS tunnel for port 8000 (free tier)
-ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 \
-    -R0:localhost:8000 free@a.pinggy.io
-
-# TCP tunnel (databases, raw SSH, etc.)
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:5432 tcp@a.pinggy.io
-
-# TLS tunnel (Pinggy can't decrypt — bring your own certs at origin)
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:443 tls@a.pinggy.io
-
-# Basic auth gate (b:user:pass)
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
-    "b:admin:secret+free@a.pinggy.io"
-
-# Bearer token gate (k:token)
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
-    "k:mysecrettoken+free@a.pinggy.io"
-
-# IP whitelist (w:CIDR)
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
-    "w:203.0.113.0/24+free@a.pinggy.io"
-
-# Enable CORS + force HTTPS redirect
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
-    "co+x:https+free@a.pinggy.io"
-
-# Pro tier (persistent URL, no 60-min cap)
-ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 "$PINGGY_TOKEN+a.pinggy.io"
-```
-
-## Procedure — Start a Tunnel and Get the URL
-
-The model SHOULD use the `terminal` tool. The tunnel must stay alive for the duration of the share, so run it as a background process and parse the public URL from stdout.
-
-### 1. Confirm a local origin is up
-
-```bash
-curl -sI http://127.0.0.1:8000/ | head -1
-# expect HTTP/1.x 200 (or any non-connection-refused response)
-```
-
-If nothing is listening yet, start it first (e.g. `python -m http.server 8000 --bind 127.0.0.1`). Pinggy will happily return a URL pointed at nothing — the user will see 502 until the origin comes up.
-
-### 2. Launch the tunnel as a background process
-
-Use `terminal(background=True)` and capture output to a logfile (Pinggy prints the URLs on stdout, then keeps the connection open):
-
-```bash
-LOG=/tmp/pinggy-8000.log
-nohup ssh -p 443 \
-    -o StrictHostKeyChecking=no \
-    -o UserKnownHostsFile=/dev/null \
-    -o ServerAliveInterval=30 \
-    -o ServerAliveCountMax=3 \
-    -R0:localhost:8000 free@a.pinggy.io \
-    > "$LOG" 2>&1 &
-echo $! > /tmp/pinggy-8000.pid
-```
-
-`StrictHostKeyChecking=no` + `UserKnownHostsFile=/dev/null` skips the first-run host-key prompt. `ServerAliveInterval=30` keeps the SSH session from getting torn down by an idle NAT.
-
-### 3. Parse the URL out of the log
-
-```bash
-sleep 4
-grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-8000.log | head -1
-```
-
-Expected output looks like:
-
-```
-You are not authenticated.
-Your tunnel will expire in 60 minutes.
-http://yqycl-98-162-69-48.a.free.pinggy.link
-https://yqycl-98-162-69-48.a.free.pinggy.link
-```
-
-Hand the `https://...pinggy.link` URL to the user.
-
-### 4. Verify
-
-```bash
-curl -sI https://<the-url>/ | head -3
-# expect 200/302/whatever the local origin actually returns
-```
-
-If you get `502 Bad Gateway`, the SSH session is up but the local origin isn't listening — fix step 1 first.
-
-### 5. Teardown
-
-```bash
-kill "$(cat /tmp/pinggy-8000.pid)"
-# or, if the pid file got lost:
-pkill -f 'ssh -p 443 .* free@a\.pinggy\.io'
-```
-
-If you have a session_id from `terminal(background=True)`, prefer `process(action='kill', session_id=...)`.
-
-## Access Control via Username Keywords
-
-Pinggy stacks control flags into the SSH username separated by `+`. Always quote the whole `user@host` argument when it contains a `+`:
-
-| Keyword | Effect |
-|---------|--------|
-| `b:user:pass` | HTTP Basic auth gate |
-| `k:token` | Bearer-token header gate (`Authorization: Bearer <token>`) |
-| `w:CIDR` | IP whitelist (single IP or CIDR, repeatable) |
-| `co` | Add `Access-Control-Allow-Origin: *` (CORS) |
-| `x:https` | Force HTTPS — auto-redirect HTTP to HTTPS |
-| `a:Name:Value` | Add request header |
-| `u:Name:Value` | Update request header |
-| `r:Name` | Remove request header |
-| `qr` | Print a QR code of the URL to stdout (handy for mobile sharing) |
-
-Combine freely: `"b:admin:secret+co+x:https+free@a.pinggy.io"`.
-
-## Web Debugger (optional)
-
-Pinggy can mirror the inbound traffic to `localhost:4300` for inspection. Add a local forward to the SSH command:
-
-```bash
-ssh -p 443 -L4300:localhost:4300 -R0:localhost:8000 free@a.pinggy.io
-```
-
-Then open `http://localhost:4300` in a browser to see live request/response pairs.
-
-## Pitfalls
-
-- **60-minute hard cap on the free tier.** The SSH session terminates at the 60-minute mark; the URL goes dead. For longer shares, either use `PINGGY_TOKEN` (Pro) or auto-restart with a shell loop (note that the URL changes on every restart for free-tier).
-- **Free-tier URL is random and changes on restart.** Don't bookmark it, don't paste it into a config file. Re-parse from the log each time.
-- **Concurrent free tunnels are limited to one per source IP.** Starting a second tunnel from the same machine usually kills the first. Pro tier lifts this.
-- **`+` in usernames must be quoted.** Bare `ssh ... b:admin:secret+free@a.pinggy.io` works in bash but breaks under shells that treat `+` specially or when assembled programmatically. Always wrap in double quotes.
-- **Don't tunnel anything sensitive without an access-control flag.** A bare HTTP tunnel is reachable by anyone with the URL. Use `b:`, `k:`, or `w:` for non-public services.
-- **`process(action='log')` may miss SSH banner output.** Pinggy prints the URLs and then the SSH session goes interactive. Always redirect to a logfile and `grep` the file directly — same pattern as `cloudflared-quick-tunnel`.
-- **Host-key prompt on first run.** Default OpenSSH config asks the user to accept Pinggy's host key. Always pass `-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null` for unattended runs.
-- **TCP and TLS tunnels return a `<subdomain>.a.pinggy.online:<port>` pair, not an https URL.** Parse with a different regex (`tcp://` and a port). Don't assume every Pinggy tunnel is HTTP.
-- **Pro mode requires the token as the username, not a flag.** Use `"$PINGGY_TOKEN+a.pinggy.io"` (no `free@`). With a token you can also add `:persistent` for a stable subdomain — see `pinggy.io/docs/`.
-
-## Recipes
-
-Composite patterns combining a local origin with a Pinggy tunnel. Each recipe is self-contained — start the origin, start the tunnel, parse the URL, hand it back to the user.
-
-### Recipe 1 — Receive a webhook callback
-
-Use this when an external service (Stripe, GitHub, Discord, AgentMail, etc.) needs to POST to a publicly reachable URL during a local task.
-
-```bash
-# 1. Tiny capturing server: every request gets appended to /tmp/webhook-hits.log
-cat >/tmp/webhook-server.py <<'PY'
-import http.server, json, datetime, pathlib
-LOG = pathlib.Path("/tmp/webhook-hits.log")
-class H(http.server.BaseHTTPRequestHandler):
-    def _capture(self):
-        n = int(self.headers.get("content-length") or 0)
-        body = self.rfile.read(n).decode("utf-8", "replace") if n else ""
-        rec = {"t": datetime.datetime.utcnow().isoformat(), "path": self.path,
-               "method": self.command, "headers": dict(self.headers), "body": body}
-        with LOG.open("a") as f: f.write(json.dumps(rec) + "\n")
-        self.send_response(200); self.send_header("content-type","application/json")
-        self.end_headers(); self.wfile.write(b'{"ok":true}\n')
-    def do_GET(self): self._capture()
-    def do_POST(self): self._capture()
-    def log_message(self,*a,**k): pass
-http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever()
-PY
-nohup python /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 &
-echo $! >/tmp/webhook-server.pid
-
-# 2. Tunnel — bearer-token-gate so randos can't pollute the capture log
-nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
-    -o ServerAliveInterval=30 \
-    -R0:localhost:18080 "k:$(openssl rand -hex 12)+free@a.pinggy.io" \
-    >/tmp/webhook-pinggy.log 2>&1 &
-echo $! >/tmp/webhook-pinggy.pid
-sleep 5
-URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/webhook-pinggy.log | head -1)
-echo "Webhook URL: $URL"
-
-# 3. While the agent works, watch hits land
-tail -f /tmp/webhook-hits.log
-```
-
-Hand `$URL` to the service that needs to call you. Teardown: `kill $(cat /tmp/webhook-server.pid) $(cat /tmp/webhook-pinggy.pid)`.
-
-### Recipe 2 — Expose an MCP server over HTTP/SSE
-
-Use when a remote MCP client (Claude Desktop on another machine, a teammate's editor, etc.) needs to reach an MCP server running on the local box. Only works for MCP servers that speak HTTP transport — stdio-mode servers can't be tunneled.
-
-```bash
-# 1. Start the MCP server in HTTP mode (example: a FastMCP server on port 8765)
-nohup python my_mcp_server.py --transport http --port 8765 \
-    >/tmp/mcp-server.log 2>&1 &
-echo $! >/tmp/mcp-server.pid
-
-# 2. Tunnel with a bearer token — MCP traffic should not be open to the internet
-TOKEN=$(openssl rand -hex 16)
-nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
-    -o ServerAliveInterval=30 \
-    -R0:localhost:8765 "k:$TOKEN+free@a.pinggy.io" \
-    >/tmp/mcp-pinggy.log 2>&1 &
-echo $! >/tmp/mcp-pinggy.pid
-sleep 5
-URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/mcp-pinggy.log | head -1)
-echo "MCP URL: $URL"
-echo "Bearer token: $TOKEN"
-```
-
-The remote client connects to `$URL` with `Authorization: Bearer $TOKEN`. Hermes' own native MCP client config: `{"transport": "http", "url": "<URL>", "headers": {"Authorization": "Bearer <TOKEN>"}}`.
-
-### Recipe 3 — Expose a local LLM endpoint (Ollama / vLLM / llama.cpp)
-
-Share a local model with a remote caller (another agent, a phone, a teammate). Ollama listens on `:11434`, vLLM and llama.cpp typically on `:8000`.
-
-```bash
-# Pre-req: the model server is already running on 127.0.0.1:11434 (Ollama default)
-TOKEN=$(openssl rand -hex 16)
-nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
-    -o ServerAliveInterval=30 \
-    -R0:localhost:11434 "k:$TOKEN+co+free@a.pinggy.io" \
-    >/tmp/llm-pinggy.log 2>&1 &
-echo $! >/tmp/llm-pinggy.pid
-sleep 5
-URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/llm-pinggy.log | head -1)
-echo "Endpoint: $URL"
-echo "Token:    $TOKEN"
-
-# Verify
-curl -s "$URL/api/tags" -H "Authorization: Bearer $TOKEN" | head
-```
-
-`co` enables CORS so a browser caller can hit the endpoint. Drop `co` for backend-only callers. For an OpenAI-compatible vLLM/llama.cpp endpoint, callers use base URL `$URL/v1` with `Authorization: Bearer $TOKEN` — but note Pinggy strips/replaces nothing in the body, so the model server itself sees Pinggy's token; the local server should be configured to ignore auth (it's already on `127.0.0.1`) and let Pinggy do the gating.
-
-### Recipe 4 — Share a dev server with a one-shot password
-
-The fastest "let a teammate poke at my running app" pattern. Random password, prints once, dies when you Ctrl-C.
-
-```bash
-PASS=$(openssl rand -base64 12 | tr -d '+/=' | head -c 12)
-echo "Dev server password: $PASS"
-ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
-    -o ServerAliveInterval=30 \
-    -R0:localhost:3000 "b:dev:$PASS+co+x:https+free@a.pinggy.io"
-# URL prints to the terminal. Share URL + password. Ctrl-C to tear down.
-```
-
-`b:dev:$PASS` gates the URL with HTTP Basic auth. `x:https` forces TLS. `co` adds CORS for SPA frontends.
-
-## Verification
-
-```bash
-# End-to-end: spin up a trivial origin, tunnel it, hit it, tear down
-python -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 &
-ORIGIN_PID=$!
-
-nohup ssh -p 443 \
-    -o StrictHostKeyChecking=no \
-    -o UserKnownHostsFile=/dev/null \
-    -R0:localhost:18000 free@a.pinggy.io >/tmp/pinggy-verify.log 2>&1 &
-SSH_PID=$!
-
-sleep 5
-URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-verify.log | head -1)
-echo "URL: $URL"
-curl -sI "$URL/" | head -1
-
-kill "$SSH_PID" "$ORIGIN_PID"
-```
-
-Expected: a `pinggy.link` URL and `HTTP/2 200` on the curl head.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-setup-wizard-generator.md

@@ -1,133 +0,0 @@
----
-title: "Setup Wizard Generator — Generate a bash wizard guiding a human through manual setup"
-sidebar_label: "Setup Wizard Generator"
-description: "Generate a bash wizard guiding a human through manual setup"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Setup Wizard Generator
-
-Generate a bash wizard guiding a human through manual setup.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/devops/setup-wizard-generator` |
-| Path | `optional-skills/devops\setup-wizard-generator` |
-| Version | `1.0.0` |
-| Author | Matt Pocock (mattpocock/skills, wizard) + Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos |
-| Tags | `wizard`, `setup`, `onboarding`, `credentials`, `secrets`, `migration`, `bash`, `human-in-the-loop` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Setup Wizard Generator
-
-Generates an interactive bash **wizard**: a script that walks a human, step
-by step, through a manual procedure that is tedious to do by hand and tedious
-to re-explain every time. It opens each URL, says exactly what to click and
-copy, captures the values, writes them where they belong (`.env`, GitHub
-secrets), confirms at every stage, and shows how many stages are left.
-
-Ported from mattpocock/skills' MIT-licensed `wizard` skill.
-
-## When to Use
-
-- Provisioning infrastructure or third-party services (Stripe, Supabase,
-  DNS, OAuth apps) where only a human can click through the dashboard
-- Setting up credentials, CI secrets, or repo variables
-- One-off migrations or cutovers with irreversible human-gated steps
-- Any procedure the user will hand to a teammate to run
-
-Do NOT use for steps the agent can perform itself — do those directly.
-
-## Prerequisites
-
-- `bash`; `gh` CLI only if stages write GitHub secrets/variables
-- The library template: `templates/template.sh` in this skill's directory
-
-## Procedure
-
-### 1. Scope the procedure
-
-Work out every manual step the human must take and every value captured
-along the way. Read the repo first, don't ask cold:
-
-- Setup: `.env`, `.env.example`, `README`, `docker-compose*`, framework
-  config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference
-  is a value the wizard must produce).
-- Migration/cutover: the current state, the target state, and the
-  irreversible actions between them.
-
-Show the user the ordered stage list and the values each produces; they may
-add, drop, or reorder. Done when every stage is named in order and, for each
-captured value, you know (a) where the human gets it, (b) where it's written
-(`.env`, a GitHub secret, both, or nowhere), and (c) whether it's secret
-(hidden entry) or public.
-
-### 2. Map each stage's journey
-
-For each stage, write the precise path a human follows: which URL to open,
-what to do there, where the value is shown — e.g. "Dashboard → Developers →
-API keys → Reveal test key → copy". Where you don't know the current UI or
-exact command, say so and check the docs or ask — never invent steps that
-may not exist.
-
-### 3. Author the wizard
-
-Copy `templates/template.sh` (from this skill's directory) to the target
-path. Replace the example stage with one `stage` per step, in dependency
-order. Set `TOTAL_STAGES` to the number of stages you wrote.
-
-Library helpers: `stage`, `say`/`step`/`note`/`warn`, `open_url`,
-`ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm`,
-`banner`, `finish`. The library above the `STAGES` marker is identical in
-every wizard — never hand-edit it; that consistency is the point.
-
-Hold the bar the template sets: open the URL before asking for its value,
-`ask_secret` for anything secret, `write_env` every persisted value,
-`set_secret` only what CI actually needs, and `confirm` before anything
-irreversible. Each `stage` clears the screen — keep one focused task per
-stage so nothing the human needs scrolls away.
-
-A wizard is ephemeral by default: save it to a scratch or `scripts/` path,
-delete it when the job's done. Commit it only when the user wants a
-repeatable setup path living in the repo.
-
-### 4. Verify and hand off
-
-- `bash -n <script>`; run `shellcheck` if available; `chmod +x <script>`.
-- Do NOT run it end-to-end yourself: it opens browsers and blocks on human
-  input. Trace it statically: every value from step 1 is captured and lands
-  where step 1 said, and every `set_secret` name exactly matches a
-  `secrets.*` reference in CI.
-- Tell the user how to run it. If it's repeatable, commit it and link it
-  from the README.
-
-## Pitfalls
-
-1. **Editing the library section.** Everything above the `STAGES` marker is
-   the wizard library; author only below it.
-2. **Inventing dashboard paths.** Third-party UIs drift. If unsure of the
-   click path, verify against current docs or flag it as approximate.
-3. **`set_secret` for values CI doesn't use.** Only push to GitHub secrets
-   what a workflow actually references.
-4. **Running the wizard yourself.** It blocks on human input; static tracing
-   plus `bash -n` is the verification.
-5. **One mega-stage.** Screen clearing per stage means a long stage scrolls
-   critical instructions away; split it.
-
-## Verification
-
-- [ ] Stage list confirmed with the user before authoring
-- [ ] `bash -n` passes; script is executable
-- [ ] Every captured value traced to its declared destination
-- [ ] Every `set_secret` name matches a CI `secrets.*` reference
-- [ ] Library section untouched from the template

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-watchers.md

@@ -1,126 +0,0 @@
----
-title: "Watchers — Poll RSS, JSON APIs, and GitHub with watermark dedup"
-sidebar_label: "Watchers"
-description: "Poll RSS, JSON APIs, and GitHub with watermark dedup"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Watchers
-
-Poll RSS, JSON APIs, and GitHub with watermark dedup.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/devops/watchers` |
-| Path | `optional-skills/devops\watchers` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos |
-| Tags | `cron`, `polling`, `rss`, `github`, `http`, `automation`, `monitoring` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Watchers
-
-Poll external sources on an interval and react only to new items. Three ready-made scripts plus a shared watermark helper; wire them into a cron job (or run them ad-hoc from the terminal).
-
-## When to Use
-
-- User wants to watch an RSS/Atom feed and be notified of new entries
-- User wants to watch a GitHub repo's issues / pulls / releases / commits
-- User wants to poll an arbitrary JSON endpoint and get notified on new items
-- User asks for "a watcher for X" or "notify me when X changes"
-
-## Mental model
-
-A watcher is just a script that:
-
-1. Fetches data from the external source
-2. Compares against a watermark file of previously-seen IDs
-3. Writes the new watermark back
-4. Prints new items to stdout (or nothing on no-change)
-
-The scripts below handle all three. The agent runs them via the terminal tool — from a cron job, a webhook, or an interactive chat — and reports what's new.
-
-## Ready-made scripts
-
-All three live in `$HERMES_HOME/skills/devops/watchers/scripts/` once the skill is installed. Each reads `WATCHER_STATE_DIR` (defaults to `$HERMES_HOME/watcher-state/`) for its state file, keyed by the `--name` argument.
-
-| Script | What it watches | Dedup key |
-|---|---|---|
-| `watch_rss.py` | RSS 2.0 or Atom feed URL | `<guid>` / `<id>` |
-| `watch_http_json.py` | Any JSON endpoint returning a list of objects | Configurable id field |
-| `watch_github.py` | GitHub issues / pulls / releases / commits for a repo | `id` / `sha` |
-
-All three:
-
-- First run records a baseline — never replays existing feed
-- Watermark is a bounded ID set (max 500) to cap memory
-- Output format: `## <title>\n<url>\n\n<optional body>` per item
-- Empty stdout on no-new — the caller treats that as silent
-- Non-zero exit on fetch errors
-
-## Usage
-
-Run a watcher directly from the terminal tool:
-
-```bash
-python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \
-  --name hn --url https://news.ycombinator.com/rss --max 5
-```
-
-Watch a GitHub repo (set `GITHUB_TOKEN` in `${HERMES_HOME:-~/.hermes}/.env` to avoid the 60 req/hr anonymous rate limit):
-
-```bash
-python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \
-  --name hermes-issues --repo NousResearch/hermes-agent --scope issues
-```
-
-Poll an arbitrary JSON API:
-
-```bash
-python $HERMES_HOME/skills/devops/watchers/scripts/watch_http_json.py \
-  --name api --url https://api.example.com/events \
-  --id-field event_id --items-path data.events
-```
-
-## Wiring into cron
-
-Ask the agent to schedule a cron job with a prompt like:
-
-> Every 15 minutes, run `watch_rss.py --name hn --url https://news.ycombinator.com/rss`. If it prints anything, summarize the headlines and deliver them. If it prints nothing, stay silent.
-
-The agent invokes the script via the terminal tool inside the cron job's agent loop; no changes to cron's built-in `--script` flag are needed.
-
-## State files
-
-Every watcher writes `$HERMES_HOME/watcher-state/<name>.json`. Inspect:
-
-```bash
-cat $HERMES_HOME/watcher-state/hn.json
-```
-
-Force a replay (next run treated as first poll):
-
-```bash
-rm $HERMES_HOME/watcher-state/hn.json
-```
-
-## Writing your own
-
-All three scripts use the same template: load watermark, fetch, diff, save, emit. `scripts/_watermark.py` is the shared helper; import it to get atomic writes + bounded ID set + first-run baseline for free. See any of the three reference scripts for how little boilerplate it takes.
-
-## Common Pitfalls
-
-1. **Printing a "no new items" header every tick.** Callers rely on empty stdout = silent. If you print anything on an empty delta, you spam the channel. The shipped scripts handle this; custom scripts must too.
-2. **Expecting the first run to emit items.** It won't — first run records a baseline. If you need an initial digest, delete the state file after the first run or add a `--prime-with-latest N` flag in your own script.
-3. **Unbounded watermark growth.** The shared helper caps at 500 IDs. Raise it for high-churn feeds; lower it on constrained filesystems.
-4. **Putting the state dir where the agent's sandbox can't write.** `$HERMES_HOME/watcher-state/` is always writable. Docker/Modal backends may not see arbitrary host paths.