docs(tunnel): document ngrok *.ngrok-free.dev block + alternative hosts (#924)

Multiple Iran-ISP users (#924 Recruit1992, #913 ehsan272727) report that
ngrok's free tier now exclusively hands out *.ngrok-free.dev domains for
new accounts, with no path to claim the older *.ngrok-free.app TLD. Some
Iran ISPs (TCI, Irancell, IRMCI confirmed) block *.ngrok-free.dev at DNS
or TCP. Symptom: curl from Iran network to ngrok URL times out, but works
from non-Iran.

Updates README.md and ngrok.md to:

1. Note the ngrok TLD shift (.app grandfathered, .dev for new accounts).
2. List ISPs confirmed to block *.ngrok-free.dev.
3. Add an "Alternative hosts" section recommending HuggingFace Spaces
   (Docker SDK) as the most Iran-friendly option in 2026 — permanent
   *.hf.space URL with no tunnel layer.
4. Update the URL behavior column for Method 2 since ngrok now gives a
   permanent dev domain by default (not "new URL each session").

No code changes — docs only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

assets/github-actions-tunnel/README.md

@@ -31,25 +31,47 @@ its own guide with step-by-step instructions.
 | # | Method | Guide | Account Required | URL Behavior | Iran ISP friendly? |
 |---|---|---|---|---|---|
 | 1 | cloudflared Quick Tunnel | [cloudflared-quick.md][quick] | None | New URL each session | ⚠️ See note below |
-| 2 | ngrok Tunnel | [ngrok.md][ngrok] | ngrok (free) | New URL each session | ✅ Works |
+| 2 | ngrok Tunnel | [ngrok.md][ngrok] | ngrok (free) | **Permanent URL** | ⚠️ `.dev` TLD blocked on some ISPs |
 | 3 | cloudflared Named Tunnel | [cloudflared-named.md][named] | Cloudflare + domain | **Permanent URL** | ⚠️ See note below |
 
-> **⚠️ Important — cloudflared methods may not work from Iran ISP.** Apps Script
+> **⚠️ ngrok `*.ngrok-free.dev` block (early 2026).** Free-tier ngrok now
-> outbound runs from Google datacenter IPs, which Cloudflare's anti-bot system
+> auto-assigns `*.ngrok-free.dev` domains exclusively for new accounts (the
-> flags as bots and serves a 403 / Persian Google Docs error page (#849). This
+> older `*.ngrok-free.app` is grandfathered for existing accounts only and
-> blocks the Apps Script → trycloudflare.com / your-domain step. **If you're on
+> cannot be claimed). Some Iran ISPs (TCI, Irancell, IRMCI confirmed via
-> Iran ISP, start with Method 2 (ngrok) instead** — ngrok's edge IPs are not
+> #924) block `*.ngrok-free.dev` at DNS or TCP. Symptom: `curl` from your
-> on Cloudflare's flagged list. cloudflared Methods 1 and 3 may still work for
+> network to your ngrok URL times out, but works from a non-Iran machine.
-> users on networks where Cloudflare's anti-bot heuristics aren't firing
+> Workarounds: try **Method 1 (cloudflared Quick)** as a different TLD, or
-> against Apps Script's outbound, so they're documented for completeness.
+> pay $10/mo for ngrok Personal plan to get `*.ngrok.app` instead.
+>
+> **⚠️ cloudflared methods may not work from Iran ISP.** Apps Script
+> outbound runs from Google datacenter IPs, which Cloudflare's anti-bot
+> system sometimes flags as bots and serves a 403 / Persian Google Docs
+> error page (#849). cloudflared Methods 1 and 3 may still work for users
+> on networks where Cloudflare's anti-bot heuristics aren't firing against
+> Apps Script's outbound — try them and check.
 
-**New to Full tunnel mode?** If you're on Iran ISP, start with [Method 2 (ngrok)][ngrok]
+**New to Full tunnel mode?** Try [Method 2 (ngrok)][ngrok] first — it's the
-— it's the most reliable. If you're on a network where CF anti-bot doesn't
+fastest setup and gives a permanent URL on the free tier. If `*.ngrok-free.dev`
-fire against Google datacenter IPs, [Method 1 (cloudflared Quick)][quick] is
+is blocked on your ISP (curl times out), switch to [Method 1 (cloudflared
-the simplest (no third-party signup).
+Quick)][quick] — different TLD, sometimes passes where ngrok's `.dev`
+doesn't. If both fail, see the **Alternative hosts** section below.
 
-**Need a stable URL that survives restarts?** Use [Method 3][named] — requires
+**Need a stable URL on a CF-friendly domain?** Use [Method 3][named] — requires
-a one-time Cloudflare CLI setup but the URL never changes.
+a one-time Cloudflare CLI setup with your own domain.
+
+## Alternative hosts (when GitHub Actions tunnels don't work)
+
+If both ngrok and cloudflared paths are blocked on your network, run
+`mhrv-tunnel-node` somewhere that doesn't rely on a third-party tunnel:
+
+- **HuggingFace Spaces (Docker SDK)**: free, permanent `*.hf.space` URL,
+  no tunnel layer needed. Create a Space → pick Docker SDK → small
+  Dockerfile that runs `ghcr.io/therealaleph/mhrv-tunnel-node:latest`.
+  16 GB storage, 2 vCPU. Most Iran-friendly option in 2026.
+- **Replit (Deno repl)**: signup with email, free tier. Run
+  `mhrv-tunnel-node` and the Repl exposes a public URL.
+- **Your own VPS**: Hetzner / Vultr / DigitalOcean / ArvanCloud. ~$3-5/mo.
+  See [tunnel-node README](../../tunnel-node/README.md) for Docker setup.
 
 ## Shared Requirements
 

assets/github-actions-tunnel/ngrok.md

@@ -100,26 +100,29 @@ The tunnel shuts down after 6 hours. To start a new session:
 1. Go to the **Actions** tab
 2. Select **Full Tunnel (ngrok)**
 3. Click **Run workflow > Run workflow**
-4. Check the tunnel URL in the logs:
+4. Check the tunnel URL in the logs. Each ngrok free account gets one
-   - **Free tier with a static domain assigned** (default for new ngrok accounts):
+   auto-assigned **dev domain** that's permanent across runs — the URL is the
-     the URL is the same across runs — no `CodeFull.gs` update needed.
+   same every time you re-run the workflow, so no `CodeFull.gs` update is
-   - **Free tier without a static domain** (older ngrok accounts, or after
+   needed after the initial setup.
-     `ngrok config delete-domain`): the URL is a fresh random
-     `*.ngrok-free.app` each time. Copy it and update `TUNNEL_SERVER_URL`
-     in `CodeFull.gs`, then redeploy.
 
 ## Limitations
 
 - Requires an ngrok account (free tier: 1 online tunnel, limited connections
-  per minute)
+  per minute).
-- ngrok's free tier now includes one **static domain** per account, so the
+- **ngrok TLD note**: ngrok handed out `*.ngrok-free.app` domains until early
-  `*.ngrok-free.app` URL stays the same across workflow runs once assigned.
+  2026; new free-tier accounts now get `*.ngrok-free.dev` instead, with no
-  Older accounts that opted out, or accounts that explicitly deleted the
+  way to switch back. **Some Iran ISPs block `*.ngrok-free.dev` at the DNS
-  domain, get a fresh URL on every run and must redeploy `CodeFull.gs` each
+  layer.** If your tunnel works on a non-Iran network but `curl` from your
-  session.
+  Iran network times out at TCP, the `.dev` block is why. Workarounds:
-- 6-hour maximum per session (GitHub Actions limit)
+  - Switch to **cloudflared Quick** (Method 1) — different TLD, often passes
+    where ngrok's `.dev` doesn't.
+  - Switch to **HuggingFace Spaces (Docker)** — run tunnel-node directly on
+    a Space, get a permanent `*.hf.space` URL with no tunnel layer.
+  - Pay for ngrok's $10/mo Personal plan to get a `*.ngrok.app` domain
+    (the older, more widely allowlisted TLD).
+- 6-hour maximum per session (GitHub Actions limit).
 - Slightly higher latency than cloudflared methods (extra hop through ngrok's
-  relay servers)
+  relay servers).
 
 ## Troubleshooting