Discovery endpoint: surface canonical PR submission flow

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.15.9] — 2026-06-04
+
+### Changed
+- **`GET /` discovery payload** (`app/main.py`): added `repo` (https://github.com/PunchTheDev/forge) and a new `agent_submission` block with `canonical` (fork + PR via `agents/<name>/agent.py`) and `direct_post` (CI/programmatic only) descriptions. `quickstart` rewritten to a numbered 3-step flow that ends at the PR path, not at `POST /submissions`. Was misleading: the bare endpoint list under "submit: POST /submissions" + the old quickstart ("Submit agent results to POST /submissions") implied direct posting was the primary entry — but the leaderboard's fork-and-beat flywheel depends on agents being submitted as open-sourced PRs. The endpoint stays open for CI/replays; the discovery copy now makes the canonical path explicit.
+
+### Tests
+- `test_root_discovery` extended: asserts `repo`, `agent_submission.canonical` (must mention "pull request"), and `agent_submission.direct_post`. Test count unchanged at 139.
+
+---
+
 ## [0.15.8] — 2026-06-04
 
 ### Changed

app/main.py

@@ -20,7 +20,7 @@ async def lifespan(app: FastAPI):
 app = FastAPI(
     title="Forge API",
     description="Competitive parametric CAD benchmark — specs, submissions, leaderboard, SOTA.",
-    version="0.15.8",
+    version="0.15.9",
     lifespan=lifespan,
 )
 
@@ -103,6 +103,7 @@ async def root():
             "openapi": "/openapi.json",
         },
         "dashboard": "https://forge.gittensor.io",
+        "repo": "https://github.com/PunchTheDev/forge",
         "endpoints": {
             "active_rounds": "/rounds/active",
             "rounds": "/rounds",
@@ -114,8 +115,22 @@ async def root():
             "health": "/health",
             "health_deep": "/health/deep",
         },
+        "agent_submission": {
+            "canonical": (
+                "Fork https://github.com/PunchTheDev/forge, add your agent under "
+                "agents/<your-name>/agent.py, and open a pull request. CI runs the "
+                "eval and posts results to this API on merge."
+            ),
+            "direct_post": (
+                "POST /submissions accepts a STEP file + score directly; intended "
+                "for CI and programmatic re-runs, not as the primary entry path "
+                "(open-source PR submissions power the leaderboard's fork-and-beat flywheel)."
+            ),
+        },
         "quickstart": (
-            "Start at GET /rounds/active to see open competitions, then "
-            "GET /specs to list problems. Submit agent results to POST /submissions."
+            "1) GET /rounds/active to see open competitions. "
+            "2) GET /specs to list problems and their constraints. "
+            "3) Fork github.com/PunchTheDev/forge and open a PR with your agent in agents/ — "
+            "CI evaluates and submits results automatically."
         ),
     }

tests/test_health.py

@@ -156,3 +156,8 @@ def test_root_discovery(client):
     assert body["endpoints"]["overall_leaderboard"] == "/leaderboard/overall"
     assert body["endpoints"]["submit"].startswith("POST")
     assert "quickstart" in body
+    # Canonical submission path: PR-based, with direct POST clearly marked as secondary.
+    assert body["repo"] == "https://github.com/PunchTheDev/forge"
+    assert "canonical" in body["agent_submission"]
+    assert "pull request" in body["agent_submission"]["canonical"].lower()
+    assert "direct_post" in body["agent_submission"]