From 0431d729cf385e14af2a5d12b731a6b8551aba06 Mon Sep 17 00:00:00 2001
From: Samuel James <samueljamesinc@gmail.com>
Date: Thu, 23 Jul 2026 20:05:27 +0000
Subject: [PATCH] docs: add screenshot reference guide

---
 docs/screenshot-guide.md | 99 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 docs/screenshot-guide.md

diff --git a/docs/screenshot-guide.md b/docs/screenshot-guide.md
new file mode 100644
index 0000000..e27938a
--- /dev/null
+++ b/docs/screenshot-guide.md
@@ -0,0 +1,99 @@
+# Screenshot & Send to Telegram — Reference
+
+## How it works
+
+1. Use **Playwright** (Python async) to launch headless Chromium
+2. Navigate to the target URL, wait for page load
+3. Take a full-page screenshot, save to /tmp/screenshot.png
+4. Use **httpx** to POST the image to Telegram Bot API `sendPhoto`
+
+## Dependencies
+
+requirements.txt:
+```
+playwright
+httpx
+```
+
+System (must be installed once on the runner):
+```bash
+pip install playwright
+python -m playwright install chromium
+python -m playwright install-deps chromium
+```
+
+## Telegram sendPhoto API
+
+```
+POST https://api.telegram.org/bot{BOT_TOKEN}/sendPhoto
+Content-Type: multipart/form-data
+
+Fields:
+  chat_id: -1004385538803  (AI Dev Team Comms group)
+  caption: "Screenshot of {url}"
+  photo: (binary file upload, field name "photo")
+```
+
+Bot token: 8865512961:AAG4VVJk7S58oAF5Ps00xgwfoPjXobbcm1E (MARSHAL bot)
+
+## Minimal working script
+
+```python
+import asyncio
+import sys
+import httpx
+from playwright.async_api import async_playwright
+
+BOT_TOKEN = "8865512961:AAG4VVJk7S58oAF5Ps00xgwfoPjXobbcm1E"
+CHAT_ID = "-1004385538803"
+URL = sys.argv[1] if len(sys.argv) > 1 else "https://www.google.com"
+
+async def main():
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+        page = await browser.new_page()
+        await page.goto(URL, wait_until="networkidle", timeout=30000)
+        await page.screenshot(path="/tmp/screenshot.png", full_page=True)
+        await browser.close()
+
+    with open("/tmp/screenshot.png", "rb") as f:
+        resp = httpx.post(
+            f"https://api.telegram.org/bot{BOT_TOKEN}/sendPhoto",
+            data={"chat_id": CHAT_ID, "caption": f"Screenshot of {URL}"},
+            files={"photo": ("screenshot.png", f, "image/png")},
+            timeout=30.0,
+        )
+    if resp.json().get("ok"):
+        print(f"[+] Screenshot of {URL} sent to Telegram")
+    else:
+        print(f"[-] Failed: {resp.text}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Usage: `python screenshot_scout.py https://linux.org`
+
+## Success criteria
+
+The task is DONE when the screenshot image appears in the Telegram group.
+Not when code is written. Not when it compiles. When the IMAGE IS IN TELEGRAM.
+
+## What can go wrong
+
+| Problem | Fix |
+|---------|-----|
+| Chromium not installed | `python -m playwright install chromium` |
+| System deps missing | `python -m playwright install-deps chromium` |
+| Timeout on slow sites | Increase timeout from 30000ms |
+| Telegram 400 error | Check chat_id is correct, bot is member of group |
+| Large screenshot >10MB | Use `quality=80` or `type="jpeg"` in screenshot() |
+
+## For MARSHAL / CODER
+
+When a task says "take a screenshot of X" or "screenshot X and send to Telegram":
+- The URL is the argument (default google.com if none given)
+- Use this exact pattern — it works, it's tested, don't reinvent it
+- requirements.txt = playwright + httpx
+- Entry point accepts URL as sys.argv[1]