docs: add screenshot reference guide

.gitea/workflows/ci.yaml

@@ -0,0 +1,12 @@
+name: CI
+on: [pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install -r requirements.txt
+      - run: python -m py_compile screenshot_scout.py

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]

screenshot_scout.py

@@ -0,0 +1,56 @@
+import asyncio
+import httpx
+from playwright.async_api import async_playwright, TimeoutError as PlaywrightTimeoutError
+
+SCREENSHOT_PATH = "/tmp/screenshot.png"
+TELEGRAM_BOT_TOKEN = "8865512961:AAG4VVJk7S58oAF5Ps00xgwfoPjXobbcm1E"
+TELEGRAM_CHAT_ID = "-1004385538803"
+TELEGRAM_API_URL = f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendPhoto"
+TARGET_URL = "https://www.google.com"
+
+
+async def capture_screenshot() -> bool:
+    try:
+        async with async_playwright() as p:
+            browser = await p.chromium.launch(headless=True)
+            page = await browser.new_page()
+            await page.goto(TARGET_URL, wait_until="networkidle", timeout=30000)
+            await page.screenshot(path=SCREENSHOT_PATH, full_page=True)
+            await browser.close()
+            print(f"[+] Screenshot saved to {SCREENSHOT_PATH}")
+            return True
+    except PlaywrightTimeoutError:
+        print(f"[-] Timeout loading {TARGET_URL}")
+        return False
+    except Exception as e:
+        print(f"[-] Error: {e}")
+        return False
+
+
+def send_screenshot() -> bool:
+    try:
+        with open(SCREENSHOT_PATH, "rb") as photo:
+            with httpx.Client(timeout=30.0) as client:
+                resp = client.post(
+                    TELEGRAM_API_URL,
+                    data={"chat_id": TELEGRAM_CHAT_ID, "caption": f"Screenshot of {TARGET_URL}"},
+                    files={"photo": ("screenshot.png", photo, "image/png")},
+                )
+        if resp.status_code == 200 and resp.json().get("ok"):
+            print("[+] Screenshot sent to Telegram!")
+            return True
+        else:
+            print(f"[-] Telegram error: {resp.text}")
+            return False
+    except Exception as e:
+        print(f"[-] Send failed: {e}")
+        return False
+
+
+async def main():
+    if await capture_screenshot():
+        send_screenshot()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())