feat(skill): add reddit best-time-to-post skill for Fortress MCP

Parameterized helper (subreddit + post count) that reads a subreddit's top
posts from old.reddit through the Fortress engine and reports the day/hour
distribution of the winners in any timezone. Uses old.reddit HTML for exact
data-timestamp/data-score because the .json API hard-blocks flagged IPs.

Author: Arman-Luthra

mcp/skill/reddit/best-time/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: reddit-best-time-to-post
+description: >-
+  Use when someone wants the best day and time to post in a subreddit, or asks to
+  analyze a subreddit's posting-time patterns. Drives the Fortress stealth engine to
+  read a subreddit's top posts (all/year/month/week) from old.reddit, extracts each
+  post's exact submission time and score, and reports the day-of-week and hour-of-day
+  distribution of the winners in any timezone. Takes two inputs: the subreddit and the
+  number of posts to analyze.
+---
+
+# Reddit best-time-to-post skill
+
+## When to use this
+Someone asks a version of "when should I post in r/X" or "what's the best time to post
+in this subreddit," or wants the posting-time pattern of a community. This skill answers
+it from data rather than folklore.
+
+## Inputs
+- **subreddit** (required): the community, without `r/` (for example `DataHoarder`).
+- **posts** (required): how many top posts to analyze. 300 to 700 gives a stable pattern.
+  Fewer is faster but noisier; more flattens out past a few hundred.
+- **tz** (optional): the IANA timezone for the report, default `America/New_York`. Use the
+  timezone the person cares about, for example `America/Los_Angeles` for Pacific.
+
+## Why this works, and its one limit
+Reddit's top listings are the posts that won. Reading when those posts were submitted gives
+a strong proxy for the best time to post. The limit is survivorship: the data shows when
+hits landed, not the posts that flopped at the same hours. Treat the result as "when
+successful posts tend to go up," not a guarantee.
+
+Source is `old.reddit.com`, not the `.json` API. Reddit's JSON endpoint and normal request
+paths hard-block datacenter and flagged IPs, but old.reddit's HTML carries exact
+`data-timestamp` (epoch milliseconds) and `data-score` attributes, so the times are precise
+instead of relative estimates like "3 hours ago." The Fortress stealth engine loads
+old.reddit without tripping the block page.
+
+## Setup
+```bash
+pip install "tilion[mcp]" playwright
+```
+No `playwright install` is needed. The script connects to Fortress over CDP rather than
+launching Playwright's own browser. On macOS the engine runs as a Docker image, so a Docker
+daemon must be running (`colima start` if you use Colima). See [`mcp/README.md`](../../README.md#macos-setup-apple-silicon-and-intel).
+
+## Run it
+```bash
+python best_time.py --subreddit DataHoarder --posts 600 --tz America/Los_Angeles
+```
+The script starts a Fortress instance on port 9400 (override with `--port` if that is taken),
+pages through the top listings until it has the requested number of unique posts, and prints
+the analysis. Roughly 100 posts per page load, with a short politeness pause between pages,
+so 600 posts takes well under a minute once the engine is warm.
+
+## Reading the output
+The report has three parts and a recommendation:
+- **Day of week**: the share of top posts on each day, plus the average score. The day with
+  the largest share is the safest bet.
+- **Hour of day**: the share of top posts in each hour, in the requested timezone. Look for
+  the plateau of high-share hours, not a single spike.
+- **Top three-hour windows**: the day-and-hour blocks that produced the most top posts. The
+  first row is the single strongest window.
+
+The final `RECOMMENDATION` line names the best day and the best three-hour window. Ignore any
+hour that shows a high average score but a tiny post count, since one viral thread skews it.
+
+## If it returns nothing
+The subreddit may be private or quarantined, or the engine may be down. On macOS the usual
+cause is a stopped Docker daemon, so run `colima start` and retry. For a genuinely hard block,
+route the engine through a residential proxy with `TILION_PROXY` before running.
+
+## Reference
+Fortress tools and setup: [`mcp/README.md`](../../README.md).
+General stealth-browser skill: [`mcp/skill/SKILL.md`](../../skill/SKILL.md).

mcp/skill/reddit/best-time/best_time.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Best time to post in a subreddit, inferred from when its top posts were submitted.
+
+Pulls the subreddit's top listings (all / year / month / week) through the Fortress
+stealth engine, reads each post's exact submission time and score, and reports the
+day-of-week and hour-of-day distribution of the winners.
+
+Why old.reddit: Reddit's `.json` API and normal request paths hard-block datacenter and
+flagged IPs, but old.reddit's HTML carries exact `data-timestamp` (epoch ms) and
+`data-score` attributes, so the times are precise rather than "3 hours ago" estimates.
+
+Usage:
+    python best_time.py --subreddit DataHoarder --posts 600
+    python best_time.py --subreddit selfhosted --posts 300 --tz America/Los_Angeles
+
+Requires:  pip install "tilion[mcp]" playwright
+    (no `playwright install` needed — it connects to Fortress over CDP, it does not
+     launch Playwright's own browser.)
+"""
+import argparse, sys, time, collections
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
+
+from tilion_fortress import Fortress
+from playwright.sync_api import sync_playwright
+
+FRAMES = ["all", "year", "month", "week"]  # widest first: biggest hits lead the sample
+MAX_PAGES_PER_FRAME = 10                    # Reddit caps top pagination near 1000 posts
+DOW = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+EXTRACT = """() => {
+  const out = [];
+  document.querySelectorAll('div.thing[data-timestamp]').forEach(el => {
+    if (el.getAttribute('data-promoted') === 'true') return;   // skip ads
+    out.push({ts:  +el.getAttribute('data-timestamp'),
+              score:+el.getAttribute('data-score'),
+              id:    el.getAttribute('data-fullname')});
+  });
+  return out;
+}"""
+
+
+def scrape(subreddit, target, port, pause):
+    """Return {id: (ts_ms, score)} until `target` unique posts or the listings run dry."""
+    posts = {}
+    with Fortress(port=port) as f:
+        with sync_playwright() as p:
+            browser = p.chromium.connect_over_cdp(f.cdp_url)
+            ctx = browser.contexts[0] if browser.contexts else browser.new_context()
+            page = ctx.new_page()
+            for t in FRAMES:
+                after, count = "", 0
+                for _ in range(MAX_PAGES_PER_FRAME):
+                    url = (f"https://old.reddit.com/r/{subreddit}/top/?sort=top&t={t}"
+                           f"&limit=100&count={count}" + (f"&after={after}" if after else ""))
+                    page.goto(url, wait_until="domcontentloaded", timeout=60000)
+                    try:
+                        page.wait_for_selector("div.thing[data-timestamp]", timeout=15000)
+                    except Exception:
+                        break  # blocked or empty listing for this frame
+                    rows = page.evaluate(EXTRACT)
+                    if not rows:
+                        break
+                    for r in rows:
+                        posts.setdefault(r["id"], (r["ts"], r["score"]))
+                    after, count = rows[-1]["id"], count + len(rows)
+                    time.sleep(pause)
+                    if len(posts) >= target:
+                        return posts
+                print(f"  [{t}] running total: {len(posts)} unique", file=sys.stderr)
+                if len(posts) >= target:
+                    break
+    return posts
+
+
+def report(posts, subreddit, tzname):
+    tz = ZoneInfo(tzname)
+    dow_c, dow_s = collections.Counter(), collections.Counter()
+    hr_c, hr_s = collections.Counter(), collections.Counter()
+    slot = collections.Counter()
+    for ts, score in posts.values():
+        dt = datetime.fromtimestamp(ts / 1000, tz=timezone.utc).astimezone(tz)
+        dow_c[dt.weekday()] += 1; dow_s[dt.weekday()] += score
+        hr_c[dt.hour] += 1;       hr_s[dt.hour] += score
+        slot[(dt.weekday(), dt.hour // 3 * 3)] += 1
+
+    total = len(posts)
+    print(f"\n===== r/{subreddit}: {total} unique top posts (times in {tzname}) =====\n")
+
+    print("DAY OF WEEK        share of top posts        avg score")
+    peak = max(dow_c.values())
+    for d in range(7):
+        c = dow_c[d]; avg = dow_s[d] / c if c else 0
+        print(f"  {DOW[d]}  {c:4d} ({c/total*100:4.1f}%)  {'#'*round(c/peak*30):30s}  {avg:6.0f}")
+
+    print(f"\nHOUR OF DAY ({tzname})   share                avg score")
+    peak = max(hr_c.values())
+    for h in range(24):
+        c = hr_c[h]
+        if not c:
+            continue
+        print(f"  {h:02d}:00  {c:4d} ({c/total*100:4.1f}%)  {'#'*round(c/peak*24):24s}  {hr_s[h]/c:6.0f}")
+
+    print("\nTOP THREE-HOUR WINDOWS BY COUNT")
+    for (d, hb), c in slot.most_common(9):
+        print(f"  {DOW[d]} {hb:02d}:00-{hb+3:02d}:00   {c:3d} posts ({c/total*100:.1f}%)")
+
+    best_day = max(range(7), key=lambda d: dow_c[d])
+    (bd, bh), _ = slot.most_common(1)[0]
+    print(f"\nRECOMMENDATION: best day is {DOW[best_day]}; single best window is "
+          f"{DOW[bd]} {bh:02d}:00-{bh+3:02d}:00 {tzname}.")
+    print("Note: this is when winning posts were submitted (survivorship). Windows with a "
+          "high avg score but few posts are outliers, not targets.")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Find the best time to post in a subreddit.")
+    ap.add_argument("--subreddit", required=True, help="subreddit name without r/ (e.g. DataHoarder)")
+    ap.add_argument("--posts", type=int, default=500, help="target number of top posts to analyze")
+    ap.add_argument("--tz", default="America/New_York", help="IANA timezone for the report")
+    ap.add_argument("--port", type=int, default=9400, help="Fortress port (avoid 9222 if the MCP server is up)")
+    ap.add_argument("--pause", type=float, default=1.5, help="seconds between page loads (politeness)")
+    args = ap.parse_args()
+
+    print(f"Scraping up to {args.posts} top posts from r/{args.subreddit} ...", file=sys.stderr)
+    posts = scrape(args.subreddit, args.posts, args.port, args.pause)
+    if not posts:
+        print("No posts scraped. The subreddit may be private/blocked, or the engine is down "
+              "(on macOS check `colima start`).", file=sys.stderr)
+        sys.exit(1)
+    report(posts, args.subreddit, args.tz)
+
+
+if __name__ == "__main__":
+    main()