Point HTML task previews at shared runner

Author: zh1peng

README.md

@@ -84,6 +84,14 @@ If both exist, the website keeps the main task card and adds:
 
 for the matched HTML companion.
 
+By default, HTML companions run through the shared `psyflow-web` GitHub Pages runner:
+
+```text
+https://taskbeacon.github.io/psyflow-web/?task=H000006-mid
+```
+
+You can override this with metadata such as `links.run_url` when needed.
+
 Rate limits:
 
 - Without a token, GitHub API requests may fail.

scripts/build-index.mjs

@@ -7,6 +7,10 @@ const TOKEN =
   process.env.GITHUB_TOKEN || process.env.GH_TOKEN || process.env.GITHUB_PAT || "";
 const PAGES_ORIGIN =
   process.env.TASKBEACON_PAGES_ORIGIN || `https://${String(ORG).toLowerCase()}.github.io`;
+const HTML_RUNNER_REPO = process.env.TASKBEACON_HTML_RUNNER_REPO || "psyflow-web";
+const HTML_RUNNER_URL =
+  process.env.TASKBEACON_HTML_RUNNER_URL ||
+  `${PAGES_ORIGIN}/${encodeURIComponent(HTML_RUNNER_REPO)}/`;
 const LOCAL_WORKSPACE_ROOT = process.env.TASKBEACON_LOCAL_WORKSPACE || path.resolve(process.cwd(), "..");
 
 const GH_API = "https://api.github.com";
@@ -258,9 +262,11 @@ function inferSlugFromRepo(repo) {
     .toLowerCase();
 }
 
-function inferPagesRunUrl(repo, explicitUrl = null) {
+function inferHtmlRunUrl(repo, explicitUrl = null) {
   if (explicitUrl) return String(explicitUrl);
-  return `${PAGES_ORIGIN}/${encodeURIComponent(String(repo ?? "").trim())}/`;
+  const url = new URL(String(HTML_RUNNER_URL));
+  url.searchParams.set("task", String(repo ?? "").trim());
+  return url.toString();
 }
 
 function isHtmlVariant(item) {
@@ -535,7 +541,7 @@ function buildTaskItem({
     last_updated,
     structure,
     readme_run_anchor: run_anchor,
-    run_url: variant === "html" ? inferPagesRunUrl(repo, explicitRunUrl) : null,
+    run_url: variant === "html" ? inferHtmlRunUrl(repo, explicitRunUrl) : null,
     web_variant: null
   };
 }
@@ -614,7 +620,7 @@ function toWebVariant(item) {
     variant: item.variant ?? null,
     release_tag: item.release_tag ?? null,
     last_updated: item.last_updated,
-    run_url: item.run_url ?? inferPagesRunUrl(item.repo),
+    run_url: item.run_url ?? inferHtmlRunUrl(item.repo),
     download_zip: downloadZipUrl(item.html_url, item.default_branch)
   };
 }

src/data/SCHEMA.md

@@ -64,5 +64,5 @@ Optional:
 - `taskbeacon.yaml` and `taskbeacon.yml` are preferred metadata sources. The indexer still accepts `task.yaml`, `task.yml`, and `task.json` for backward compatibility.
 - `short_description` is taken from metadata first, then README table fields, then the README first paragraph, then the GitHub repo description.
 - `maturity` is taken from metadata when present; otherwise it is parsed from README badges like `![Maturity: smoke_tested]`.
-- `run_url` is mainly used for standalone HTML tasks.
+- `run_url` is used for HTML tasks and web companions. By default it points to the shared `psyflow-web` GitHub Pages runner with `?task=<repo>`, unless metadata overrides it.
 - `web_variant` is attached to a main task when the indexer finds a companion repo with the same `slug` and `variant: html`.

src/data/tasks_index.json

@@ -360,7 +360,7 @@
         "variant": "html",
         "release_tag": "0.1.0",
         "last_updated": "2026-03-06T09:13:27.3316330Z",
-        "run_url": "https://taskbeacon.github.io/H000006-mid/",
+        "run_url": "https://taskbeacon.github.io/psyflow-web/?task=H000006-mid",
         "download_zip": "https://github.com/TaskBeacon/H000006-mid/archive/refs/heads/main.zip"
       }
     },