better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/security/security-web-pentest.md

@@ -0,0 +1,337 @@
+---
+title: "Web Pentest — Authorized web pentest: recon, proof-based exploits, report"
+sidebar_label: "Web Pentest"
+description: "Authorized web pentest: recon, proof-based exploits, report"
+---
+
+{/* 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. */}
+
+# Web Pentest
+
+Authorized web pentest: recon, proof-based exploits, report.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/security/web-pentest` |
+| Path | `optional-skills/security\web-pentest` |
+| Version | `1.0.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos |
+| Tags | `Security`, `Pentest`, `Web`, `Recon` |
+
+## 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.
+:::
+
+# Web Application Penetration Testing
+
+A phased pentesting workflow for running web applications. Adapted from
+Shannon's pipeline (Keygraph, AGPL — concepts only, no code borrowed).
+Built around three rules:
+
+1. No exploit, no report — every finding requires reproducible evidence.
+2. Bounded scope — every active request goes against a target the operator
+   pre-declared. Off-scope hosts are refused.
+3. Bypass exhaustion before false-positive dismissal — a "blocked" payload
+   is not a clean bill of health until you've tried the bypass set.
+
+---
+
+## ⚠️ Hard Guardrails — Read Before Every Engagement
+
+Violating any of these invalidates the engagement and may be illegal.
+
+1. **Authorization gate.** Before the first active scan in a session, you
+   MUST confirm with the user, in writing, that they own or have written
+   authorization to test the target. Record the acknowledgement in
+   `engagement/authorization.md` (see template). No acknowledgement → no
+   active scanning. Reading public pages with `curl` is fine; sending
+   payloads is not.
+
+2. **Scope allowlist.** Maintain `engagement/scope.txt` — one hostname or
+   CIDR per line. Every `nmap`, `curl`, `whatweb`, browser navigation, or
+   payload-bearing request MUST be against an entry in scope. If a target
+   redirects you off-scope (3xx to a different host, a link in HTML),
+   STOP and confirm with the user before following.
+
+3. **No production systems without paper.** If the user hasn't told you
+   "yes, prod is in scope and I have written sign-off," assume not. Default
+   targets are staging, local docker, dedicated test instances.
+
+4. **Cloud metadata is off by default.** Do not probe `169.254.169.254`,
+   `metadata.google.internal`, `100.100.100.200`, `[fd00:ec2::254]`, or
+   equivalent unless the engagement explicitly includes SSRF-to-metadata
+   as a goal AND the target is one you control. The agent's browser tool
+   can reach these from inside your own infrastructure — don't.
+
+5. **Destructive payloads need approval.** SQLi payloads that DROP/DELETE,
+   filesystem-write SSTI, command injection with `rm`/`shutdown`/`mkfs`,
+   anything that mutates beyond a single test row → ASK FIRST. The
+   `approval.py` system catches some; don't rely on it alone.
+
+6. **Aux-client leakage risk (Hermes-specific).** This skill produces
+   sessions full of SQLi/XSS/RCE payloads, captured credentials, JWT
+   tokens. Hermes' compression and title-generation paths replay history
+   through the auxiliary client (often the main model). Anything sensitive
+   you write to the conversation can leave the box on the next compress.
+   Mitigation:
+   - Redact captured tokens/credentials to the LAST 6 CHARS before logging
+     them in any message. Full values go to `engagement/evidence/` files,
+     never into chat history.
+   - If the engagement is sensitive, set `auxiliary.title_generation.enabled: false`
+     in `~/.hermes/config.yaml` for the session.
+
+7. **Rate limit yourself.** Default 200ms between active requests against
+   any single host. The recon-scan.sh script enforces this. Don't bypass
+   it without operator approval.
+
+8. **Authority of the report.** This skill produces a security
+   assessment, not a "PASS." Even a clean run is "no exploitable issues
+   FOUND in scope X within time T using methods Y" — not "the application
+   is secure." Mirror that language in the report.
+
+---
+
+## Phase 0: Engagement Setup
+
+Before any scanning happens, create the engagement directory and
+authorization acknowledgement.
+
+```bash
+ENGAGEMENT=engagement-$(date +%Y%m%d-%H%M%S)
+mkdir -p "$ENGAGEMENT"/{evidence,findings,reports}
+cd "$ENGAGEMENT"
+```
+
+1. **Ask the user (verbatim):**
+   > "Confirm: (a) the target URL is [X], (b) you own this application
+   > or have written authorization to test it, and (c) the engagement
+   > may run for up to [N] hours starting now. Reply 'authorized' to
+   > proceed."
+
+2. **Wait for explicit `authorized` response.** Any other answer means STOP.
+
+3. **Record authorization** to `engagement/authorization.md` using the
+   template in `templates/authorization.md`. Include:
+   - Target URL(s) and IP(s)
+   - Authorization basis (ownership / written authz from $name)
+   - Engagement window
+   - Out-of-scope items (production, third-party services, etc.)
+   - Operator name (the user driving this session)
+
+4. **Build scope.txt:**
+   ```
+   localhost
+   127.0.0.1
+   staging.example.com
+   192.168.1.0/24    # internal lab only, with operator OK
+   ```
+
+5. **Read** `references/scope-enforcement.md` before issuing the first
+   active request — that doc has the host-extraction rules you apply
+   to every command/URL before it goes out.
+
+---
+
+## Phase 1: Pre-Recon (Code Analysis, optional)
+
+Skip if no source access (black-box engagement).
+
+If you have read access to the application source:
+
+1. **Map the architecture** — framework, routing, middleware stack
+2. **Inventory sinks** — every `execute(`, `os.system(`, `eval(`,
+   template render, file read/write, redirect target
+3. **Map auth** — session cookie vs JWT, OAuth flows, password reset,
+   privileged endpoints
+4. **Identify trust boundaries** — what's authenticated, what's not,
+   what comes from `request.*`
+5. **Backward taint** from each sink to a request source. Early-terminate
+   when proper sanitization is found (parameterized queries, allowlists,
+   `shlex.quote`, well-known escapers).
+
+Output: `evidence/pre-recon.md` — architecture map, sink inventory,
+suspected vulnerable code paths.
+
+This is OFFLINE work. No traffic to the target.
+
+---
+
+## Phase 2: Recon (Live, Read-Only)
+
+Maps the attack surface. All requests are GETs of public pages, no
+payloads yet. Still scope-bounded.
+
+1. **Verify scope.** Resolve every target hostname → IP. Confirm IPs are
+   in scope (avoids the "DNS points somewhere unexpected" trap).
+
+2. **Network surface** (only if scope permits port scanning):
+   ```bash
+   nmap -sT -T3 --top-ports 100 -oN evidence/nmap.txt $TARGET
+   ```
+   Use `-T3` (default), not `-T4/-T5`. Stealthier and avoids tripping
+   IDS/IPS in shared environments.
+
+3. **Tech fingerprint:**
+   ```bash
+   whatweb -v $TARGET_URL > evidence/whatweb.txt
+   curl -sIk $TARGET_URL > evidence/headers.txt
+   ```
+
+4. **Endpoint discovery:**
+   - Crawl the app with the browser tool (`browser_navigate`,
+     `browser_get_images`, follow links).
+   - Inspect `robots.txt`, `sitemap.xml`, `.well-known/*`.
+   - Use the developer tools network panel via browser tool to capture
+     XHR/fetch calls.
+
+5. **Auth surface:** Identify login, registration, password reset,
+   session cookie names, token formats. Do NOT send credentials yet —
+   just observe.
+
+6. **Correlate with pre-recon** (if you have source). For each
+   `evidence/pre-recon.md` finding, mark whether the live surface
+   confirms it's reachable.
+
+Output: `evidence/recon.md` — endpoints, technologies, auth model,
+input vectors.
+
+---
+
+## Phase 3: Vulnerability Analysis
+
+One delegate_task per vulnerability class. Each agent reads
+`evidence/recon.md` (+ `evidence/pre-recon.md` if present), produces
+`findings/<class>-queue.json` using `templates/exploitation-queue.json`.
+
+Use `delegate_task` with these focused subagents (parallel where possible):
+
+| Class | Goal | Reference |
+|-------|------|-----------|
+| `injection` | SQLi, command, path traversal, SSTI, LFI/RFI, deserialization | `references/vuln-taxonomy.md` (slot types) |
+| `xss` | Reflected, stored, DOM-based | `references/vuln-taxonomy.md` (render contexts) |
+| `auth` | Login bypass, JWT confusion, session fixation, OAuth flaws | `references/exploitation-techniques.md` |
+| `authz` | IDOR, vertical/horizontal escalation, business logic | `references/exploitation-techniques.md` |
+| `ssrf` | Internal reachability, metadata, protocol smuggling | Skip metadata unless explicitly authorized |
+| `infra` | Misconfig, info disclosure, default creds, exposed admin | `references/exploitation-techniques.md` |
+
+Each queue entry has: id, vuln class, source (file:line if known),
+endpoint, parameter, slot type, suspected defense, verdict
+(`identified` / `partial` / `confirmed` / `critical`), witness payload,
+confidence (0-1), notes.
+
+The analysis phase doesn't send malicious payloads yet — it stages them.
+The exploitation phase actually fires them.
+
+---
+
+## Phase 4: Exploitation (Proof-Based, Conditional)
+
+Only run a sub-agent per class where the analysis queue has actionable
+entries (`identified` or `partial`).
+
+For each candidate:
+
+1. **Pre-send check** — host in scope? auth gate satisfied? payload
+   approved if destructive?
+2. **Send the witness payload** — minimal proof. SQLi: `' AND 1=1--`
+   then `' AND 1=2--`. XSS: a benign marker like
+   `<svg/onload=console.log("HERMES-PENTEST-XSS")>`. Never `alert(1)` in
+   stored XSS — it'll fire for other users in shared environments.
+3. **Verify the witness fires** — for blind injection, use a sleep
+   probe (`SLEEP(5)`) and time the response. For SSRF, use a
+   tester-controlled callback host you own (NOT a public service like
+   webhook.site for sensitive engagements — exfil paths).
+4. **Promote level:**
+   - **L1 Identified** — pattern matched, no behavior change
+   - **L2 Partial** — sink reached, but defense in place
+   - **L3 Confirmed** — payload changed app behavior in observable way
+   - **L4 Critical** — data extracted, code executed, access escalated
+5. **Bypass exhaustion before classifying as FP.** For each candidate
+   that blocks: try at least the bypass set in
+   `references/bypass-techniques.md` for that class. Only after the set
+   is exhausted may you write `verdict: false_positive`.
+6. **Record evidence** for every L3/L4:
+   - Full request (method, URL, headers, body)
+   - Response (status, headers, relevant body excerpt)
+   - Reproducer command (curl one-liner)
+   - Impact statement
+
+Output: `findings/exploitation-evidence.md`
+
+**Redact in evidence files:**
+- Any captured credentials/tokens → last 6 chars only in chat;
+  full value to `findings/secrets-vault.md` (gitignored).
+- Other users' PII → redact.
+- Your test credentials → fine to keep.
+
+---
+
+## Phase 5: Reporting
+
+Generate the final report using `templates/pentest-report.md`. Sections:
+
+1. Executive summary
+2. Engagement scope (from `engagement/scope.txt`)
+3. Authorization (from `engagement/authorization.md`)
+4. Findings (L3/L4 only — proof-required). Per finding:
+   - Title, severity (CVSS 3.1), CWE
+   - Affected endpoint(s)
+   - Proof (request + response excerpt)
+   - Reproduction steps
+   - Impact
+   - Remediation
+5. Not-exploited candidates (L1/L2 with notes on what blocked them)
+6. Out-of-scope observations
+7. Methodology / tools used
+8. Limitations and what was NOT tested
+
+**Severity policy:** CVSS only for L3/L4. L1/L2 are "candidates pending
+verification" — don't assign CVSS to unverified findings.
+
+---
+
+## When to Stop
+
+- The user revokes authorization.
+- A candidate finding clearly impacts production data and you don't have
+  approval for destructive testing — STOP and ask.
+- The target starts returning 503/429 storms — back off, reconvene with
+  the operator.
+- You discover something *outside* the contracted scope (e.g. an exposed
+  customer database while testing an unrelated endpoint). STOP, document,
+  report to the operator. Do not pivot without explicit approval — that
+  pivot is what makes pentesting illegal.
+
+---
+
+## What This Skill Does NOT Cover
+
+- Network-layer pentesting beyond port scanning (no Metasploit,
+  Cobalt Strike, AD attacks, network protocol fuzzing).
+- Reverse engineering / binary analysis (see issue #383).
+- Source-only static analysis (see issue #382).
+- Active social engineering / phishing.
+- Anything against systems the operator hasn't pre-authorized.
+
+If the engagement needs any of these, escalate to a professional
+pentester. This skill complements professional pentesting; it does
+not replace it.
+
+---
+
+## Further Reading
+
+- `references/scope-enforcement.md` — how to bound every active request
+- `references/vuln-taxonomy.md` — slot types, render contexts, OWASP map
+- `references/exploitation-techniques.md` — per-class payload patterns
+- `references/bypass-techniques.md` — common WAF/filter bypasses
+- `templates/authorization.md` — engagement authorization template
+- `templates/pentest-report.md` — final report template
+- `templates/exploitation-queue.json` — per-class finding queue schema
+- `scripts/recon-scan.sh` — rate-limited nmap+whatweb+headers wrapper

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/smart-home/smart-home-openhue.md

@@ -0,0 +1,127 @@
+---
+title: "Openhue — Control Philips Hue lights, scenes, rooms via OpenHue CLI"
+sidebar_label: "Openhue"
+description: "Control Philips Hue lights, scenes, rooms via OpenHue CLI"
+---
+
+{/* 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. */}
+
+# Openhue
+
+Control Philips Hue lights, scenes, rooms via OpenHue CLI.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/smart-home/openhue` |
+| Path | `optional-skills/smart-home\openhue` |
+| Version | `1.0.1` |
+| Author | community |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Smart-Home`, `Hue`, `Lights`, `IoT`, `Automation` |
+
+## 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.
+:::
+
+# OpenHue CLI
+
+Control Philips Hue lights and scenes via a Hue Bridge from the terminal.
+
+## Prerequisites
+
+```bash
+# Linux (pre-built binary — releases ship tarballs, not bare binaries)
+curl -sL "https://github.com/openhue/openhue-cli/releases/latest/download/openhue_Linux_x86_64.tar.gz" \
+  | tar -xz -C /tmp openhue \
+  && install -m 0755 /tmp/openhue ~/.local/bin/openhue
+# (use openhue_Linux_arm64.tar.gz on ARM64)
+
+# macOS
+brew install openhue/cli/openhue-cli
+```
+
+First run requires pressing the button on your Hue Bridge to pair. The bridge must be on the same local network.
+
+## When to Use
+
+- "Turn on/off the lights"
+- "Dim the living room lights"
+- "Set a scene" or "movie mode"
+- Controlling specific Hue rooms, zones, or individual bulbs
+- Adjusting brightness, color, or color temperature
+
+## Common Commands
+
+### List Resources
+
+```bash
+openhue get light       # List all lights
+openhue get room        # List all rooms
+openhue get scene       # List all scenes
+```
+
+### Control Lights
+
+```bash
+# Turn on/off
+openhue set light "Bedroom Lamp" --on
+openhue set light "Bedroom Lamp" --off
+
+# Brightness (0-100)
+openhue set light "Bedroom Lamp" --on --brightness 50
+
+# Color temperature (warm to cool: 153-500 mirek)
+openhue set light "Bedroom Lamp" --on --temperature 300
+
+# Color (by name or hex)
+openhue set light "Bedroom Lamp" --on --color red
+openhue set light "Bedroom Lamp" --on --rgb "#FF5500"
+```
+
+### Control Rooms
+
+```bash
+# Turn off entire room
+openhue set room "Bedroom" --off
+
+# Set room brightness
+openhue set room "Bedroom" --on --brightness 30
+```
+
+### Scenes
+
+```bash
+openhue set scene "Relax" --room "Bedroom"
+openhue set scene "Concentrate" --room "Office"
+```
+
+## Quick Presets
+
+```bash
+# Bedtime (dim warm)
+openhue set room "Bedroom" --on --brightness 20 --temperature 450
+
+# Work mode (bright cool)
+openhue set room "Office" --on --brightness 100 --temperature 250
+
+# Movie mode (dim)
+openhue set room "Living Room" --on --brightness 10
+
+# Everything off
+openhue set room "Bedroom" --off
+openhue set room "Office" --off
+openhue set room "Living Room" --off
+```
+
+## Notes
+
+- Bridge must be on the same local network as the machine running Hermes
+- First run requires physically pressing the button on the Hue Bridge to authorize
+- Colors only work on color-capable bulbs (not white-only models)
+- Light and room names are case-sensitive — use `openhue get light` to check exact names
+- Works great with cron jobs for scheduled lighting (e.g. dim at bedtime, bright at wake)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/social-media/social-media-reddit-reading.md

@@ -0,0 +1,146 @@
+---
+title: "Reddit Reading — Read Reddit: subreddits, search, threads, users"
+sidebar_label: "Reddit Reading"
+description: "Read Reddit: subreddits, search, threads, users"
+---
+
+{/* 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. */}
+
+# Reddit Reading
+
+Read Reddit: subreddits, search, threads, users. No browser.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/social-media/reddit-reading` |
+| Path | `optional-skills/social-media/reddit-reading` |
+| Version | `1.0.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Reddit`, `Social Media`, `Research`, `Discussions`, `Community` |
+| Related skills | [`rss-feeds`](/docs/user-guide/skills/optional/research/research-rss-feeds), [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations), [`blocked-page-recovery`](/docs/user-guide/skills/bundled/web/web-blocked-page-recovery), [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) |
+
+## 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.
+:::
+
+# Reddit Reading Skill
+
+Reads Reddit content — subreddit listings, site or subreddit search, full threads with
+comments, and user activity — from a server or headless machine where the normal routes
+are dead. It does not post, vote, or log in as a user. Idea credit: the per-platform
+backend routing in [Agent Reach](https://github.com/Panniantong/Agent-Reach).
+
+## When to Use
+
+- "What is r/LocalLLaMA saying about X", "find Reddit threads on Y", "summarise this
+  Reddit thread", "what has u/someone posted lately".
+- Any `reddit.com` URL the user shares. `web_extract`, `browser_navigate` and the
+  `.json` endpoints all fail from server IPs (403 or a "Prove your humanity" wall);
+  this skill is the working path.
+- Not for posting, voting, messaging, or anything needing a user login.
+
+## Prerequisites
+
+**None.** No Reddit account, login, cookie, or API key is needed. The default backend is
+Reddit's public Atom feeds (`.rss` endpoints), the only unauthenticated route Reddit still
+serves to non-residential IPs. It is throttled to about one request per minute per IP and
+returns thinner data (no scores, top-level comments only), which is fine for a few calls.
+
+**Optional upgrade (app credentials, still no user login):** for sustained use or full
+data, register a free "script" type app at https://www.reddit.com/prefs/apps and put its
+two values in `~/.hermes/.env`:
+
+```
+REDDIT_CLIENT_ID=...
+REDDIT_CLIENT_SECRET=...
+```
+
+This is an application registration, not a login: the script uses the app-only
+`client_credentials` grant, never a username, password, or browser cookie, and never
+acts as the user. With both values set it switches to the OAuth API automatically
+(~100 requests per minute, scores, nested comments, `num_comments`); if they are
+missing or rejected it falls back to the anonymous feeds and says so on stderr.
+
+| | Anonymous feeds (default) | OAuth app credentials |
+|---|---|---|
+| Setup | nothing | 1-minute app registration, two `.env` values |
+| Rate limit | ~1 request / minute / IP | ~100 requests / minute |
+| Thread data | post + top-level comments, no scores | nested comments, scores, comment counts |
+| Acts as a user | no | no |
+
+## How to Run
+
+Run every command through `terminal` with the skill-relative script path:
+
+```bash
+python3 scripts/reddit.py doctor                                  # which backend, current rate-limit window
+python3 scripts/reddit.py sub LocalLLaMA --sort hot --limit 15
+python3 scripts/reddit.py search "hermes agent" --sub LocalLLaMA --sort new
+python3 scripts/reddit.py thread https://www.reddit.com/r/x/comments/abc123/slug/ --limit 40
+python3 scripts/reddit.py user spez --limit 10
+python3 scripts/reddit.py --json search "topic"                  # machine-readable
+```
+
+## Quick Reference
+
+Every command works on both backends; the script chooses the backend, you never pass a flag.
+
+| Need | Command | Anonymous | OAuth |
+|---|---|---|---|
+| Subreddit front page | `sub NAME --sort hot\|new\|top\|rising [--time week]` | ✔ | ✔ |
+| Search all of Reddit | `search "q" --sort relevance\|new\|top\|comments` | ✔ | ✔ |
+| Search one subreddit | `search "q" --sub NAME` | ✔ | ✔ |
+| Thread + comments | `thread URL --limit N` | ✔ top-level only, no scores | ✔ nested, scores |
+| User posts/comments | `user NAME` | ✔ | ✔ |
+| Backend + rate limit | `doctor` | ✔ | ✔ |
+
+## Procedure
+
+① `doctor` once per task if you have not called it this session — it tells you which
+backend is live and how many seconds remain in the anonymous window.
+
+② Plan your calls before making them. Anonymous Reddit allows roughly **one request per
+minute per IP**; the script sleeps until the window resets on a 429 and retries once, so
+a five-call plan costs about five minutes. Prefer one `search --sub` over several `sub`
+listings, and read one thread rather than the whole listing.
+
+③ For "what is the community saying" questions, read the thread bodies (`thread`) rather
+than stopping at titles; the listing only carries the first ~300 characters of each post.
+
+④ Cite the permalink (`url` field), not the listing page, when the result feeds a report.
+`grounded-citations` registers these URLs like any other source.
+
+⑤ If the user needs sustained Reddit access (monitoring, more than ~10 calls), stop and
+ask them to register the app credentials (Prerequisites) rather than grinding through the
+throttle. Tell them plainly: it is a free app registration, not logging Hermes into their
+account. Never ask for a Reddit password or browser cookies.
+
+## Pitfalls
+
+- `www.reddit.com/…/.json`, `api.reddit.com` and `old.reddit.com` return 403 or an
+  empty "Welcome to Reddit" shell for datacentre IPs. Do not fall back to them; do not
+  spoof a browser User-Agent (also 403).
+- `r.jina.ai` and the `browser_navigate` tool hit the same block ("blocked by network
+  security" / humanity check). `blocked-page-recovery`'s Wayback route can still recover
+  an **old** thread that was archived; it cannot fetch fresh ones.
+- Anonymous thread feeds only contain the post plus top-level comments (Reddit caps the
+  feed at a handful of entries); scores and reply nesting are OAuth-only.
+- Reddit's `limit` on feeds is advisory — expect 5–25 entries regardless of what you ask.
+- Never paste `REDDIT_CLIENT_SECRET` into a chat or log; the script reads it from the
+  environment only.
+- Do not "fix" a 429 by retrying in a loop or adding a proxy; the throttle is per IP and
+  the script already waits out the window once. More than one 429 in a row means the
+  task needs the app credentials.
+
+## Verification
+
+`python3 scripts/reddit.py doctor` prints `anonymous_feed: ok` and an
+`x-ratelimit-reset` value; `sub announcements --limit 1` returns one entry with a
+`reddit.com/r/announcements/comments/` URL. With credentials set, `doctor` prints
+`active_backend: oauth` and `thread …` output shows numeric scores.