maveryn · maveryn · Jul 27, 2026 · Jul 27, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,13 @@
 # Contributing To Trace
 
+## Community
+
+Use [GitHub Issues](https://github.com/maveryn/trace/issues) for concrete,
+scoped work and reproducible bug reports. Use
+[GitHub Discussions](https://github.com/maveryn/trace/discussions) for
+questions, integration ideas, and reproduction reports that are not yet a
+specific change request.
+
 ## Development Setup
 
 ```bash

diff --git a/README.md b/README.md
@@ -7,14 +7,15 @@ post-training. Each example includes an image, prompt, typed answer,
 image-space annotation, verifier metadata, and execution trace. The registry
 contains 1,000 tasks across 277 scenes and 11 visual domains.
 
+Training Qwen2.5-VL-3B and 7B on 64,000 Trace instances improved the
+macro-average across 24 external benchmarks by **+3.51** and **+4.06 percentage
+points**, respectively. [See the transfer results](#external-benchmark-transfer).
+
 <p align="center">
-  <a href="https://maveryn.github.io/trace/"><img alt="Project Page" src="https://img.shields.io/badge/Project-Page-14324a?style=for-the-badge"></a>
   <a href="https://huggingface.co/spaces/maveryn/trace"><img alt="Live Demo" src="https://img.shields.io/badge/HuggingFace-Live_Demo-2563eb?style=for-the-badge"></a>
-  <a href="https://arxiv.org/abs/2607.19790"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2607.19790-b31b1b?style=for-the-badge"></a>
-  <a href="https://huggingface.co/collections/maveryn/trace-6a604291b4be4ed6399b9f24"><img alt="Hugging Face Collection" src="https://img.shields.io/badge/HuggingFace-Collection-f59e0b?style=for-the-badge"></a>
+  <a href="https://arxiv.org/abs/2607.19790"><img alt="Paper" src="https://img.shields.io/badge/arXiv-Paper-b31b1b?style=for-the-badge"></a>
   <a href="https://huggingface.co/datasets/maveryn/trace"><img alt="Dataset" src="https://img.shields.io/badge/HuggingFace-Dataset-f59e0b?style=for-the-badge"></a>
-  <a href="https://huggingface.co/maveryn/trace-qwen2.5-vl-3b"><img alt="3B Model" src="https://img.shields.io/badge/HuggingFace-3B_Model-f59e0b?style=for-the-badge"></a>
-  <a href="https://huggingface.co/maveryn/trace-qwen2.5-vl-7b"><img alt="7B Model" src="https://img.shields.io/badge/HuggingFace-7B_Model-f59e0b?style=for-the-badge"></a>
+  <a href="https://github.com/maveryn/trace/blob/main/docs/research/REPRODUCING_RESULTS.md"><img alt="Reproduce" src="https://img.shields.io/badge/Results-Reproduce-159b91?style=for-the-badge"></a>
 </p>
 
 ![Trace examples across charts, games, geometry, graphs, icons, illustrations, pages, physics, puzzles, symbolic reasoning, and 3D scenes](docs/assets/paper-domain-montage/trace-paper-domain-montage.png)
@@ -101,6 +102,9 @@ The table reports all 24 external benchmarks for the matched 3B and 7B
 comparisons. Parenthesized values are mean seed-paired TRACE-minus-Base changes
 in percentage points.
 
+<details>
+<summary><strong>View all 24 benchmark results</strong></summary>
+
 <!-- trace-eval-v1-base-trace-table:start -->
 | Benchmark | 3B Base | 3B TRACE (Δ) | 7B Base | 7B TRACE (Δ) |
 | --- | ---: | ---: | ---: | ---: |
@@ -136,12 +140,18 @@ in percentage points.
 | MME-Reasoning | 22.62 ± 1.81 | 25.06 ± 1.53 (+2.44) | 25.17 ± 1.18 | 28.03 ± 0.89 (+2.86) |
 <!-- trace-eval-v1-base-trace-table:end -->
 
+</details>
+
 The [research page](docs/research/README.md#external-benchmark-results) includes
 the full eight-model comparison. Machine-readable per-seed scores are available
 in [`results.json`](https://github.com/maveryn/trace/blob/rlvr/rlvr/evaluation/trace_eval/results.json).
 
 ## Released Models
 
+The [Trace collection](https://huggingface.co/collections/maveryn/trace-6a604291b4be4ed6399b9f24)
+groups the interactive Space, dataset, checkpoints, paper, and evaluation
+artifacts in one place.
+
 | Released checkpoint | Base model |
 | --- | --- |
 | [TRACE Qwen2.5-VL-3B](https://huggingface.co/maveryn/trace-qwen2.5-vl-3b) | [`Qwen2.5-VL-3B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) |
@@ -344,7 +354,10 @@ attributions are listed in
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, review, and pull
-request guidance.
+request guidance. Browse [open issues](https://github.com/maveryn/trace/issues)
+for scoped work, or use
+[Discussions](https://github.com/maveryn/trace/discussions) for questions,
+integration ideas, and reproduction reports.
 
 ## Licensing
 

diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -1,5 +1,13 @@
 # Development
 
+## Community
+
+Use [GitHub Issues](https://github.com/maveryn/trace/issues) for concrete,
+scoped work and reproducible bug reports. Use
+[GitHub Discussions](https://github.com/maveryn/trace/discussions) for
+questions, integration ideas, and reproduction reports that are not yet a
+specific change request.
+
 ## Source Layout
 
 - `src/trace_tasks/core/`: generation, identity, validation, trace, reward, and export infrastructure

diff --git a/docs/README.md b/docs/README.md
@@ -26,15 +26,19 @@ hide:
   trace.
 </p>
 
+<p class="trace-hero__evidence">
+  Training Qwen2.5-VL-3B and 7B on 64,000 Trace instances improved the
+  macro-average across 24 external benchmarks by <strong>+3.51</strong> and
+  <strong>+4.06 percentage points</strong>, respectively.
+  <a href="#external-benchmark-transfer">See the transfer results.</a>
+</p>
+
 <div class="trace-resource-links">
   <a class="md-button md-button--primary" href="https://huggingface.co/spaces/maveryn/trace">Live Demo</a>
   <a class="md-button" href="https://github.com/maveryn/trace">Code</a>
   <a class="md-button" href="https://arxiv.org/abs/2607.19790">Paper</a>
-  <a class="md-button" href="research/">Research</a>
-  <a class="md-button" href="https://huggingface.co/collections/maveryn/trace-6a604291b4be4ed6399b9f24">Collection</a>
   <a class="md-button" href="https://huggingface.co/datasets/maveryn/trace">Dataset</a>
-  <a class="md-button" href="https://huggingface.co/maveryn/trace-qwen2.5-vl-3b">3B Model</a>
-  <a class="md-button" href="https://huggingface.co/maveryn/trace-qwen2.5-vl-7b">7B Model</a>
+  <a class="md-button" href="research/REPRODUCING_RESULTS/">Reproduce</a>
 </div>
 </div>
 
@@ -201,6 +205,9 @@ The table reports all 24 external benchmarks for the matched 3B and 7B
 comparisons. Parenthesized values are mean seed-paired TRACE-minus-Base changes
 in percentage points.
 
+<details markdown="1">
+<summary><strong>View all 24 benchmark results</strong></summary>
+
 <!-- trace-eval-v1-base-trace-table:start -->
 | Benchmark | 3B Base | 3B TRACE (Δ) | 7B Base | 7B TRACE (Δ) |
 | --- | ---: | ---: | ---: | ---: |
@@ -236,11 +243,17 @@ in percentage points.
 | MME-Reasoning | 22.62 ± 1.81 | 25.06 ± 1.53 (+2.44) | 25.17 ± 1.18 | 28.03 ± 0.89 (+2.86) |
 <!-- trace-eval-v1-base-trace-table:end -->
 
+</details>
+
 The [research page](research/README.md#external-benchmark-results) includes the
 full eight-model comparison and links to the evaluation artifacts.
 
 ## Released models
 
+The [Trace collection](https://huggingface.co/collections/maveryn/trace-6a604291b4be4ed6399b9f24)
+groups the interactive Space, dataset, checkpoints, paper, and evaluation
+artifacts in one place.
+
 | Released checkpoint | Base model |
 | --- | --- |
 | [TRACE Qwen2.5-VL-3B](https://huggingface.co/maveryn/trace-qwen2.5-vl-3b) | [Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) |

diff --git a/docs/assets/brand/README.md b/docs/assets/brand/README.md
@@ -19,6 +19,9 @@ scene families.
   documentation headers.
 - `trace-mark-light.png`: light-theme raster used by static documentation
   composites.
+- `../social/trace-social-preview.png`: the `1280x640` solid-background
+  repository and website social preview, generated by
+  `scripts/generate_social_preview.py`.
 
 The SVG files are transparent and self-contained. Their structural ink adapts
 to the viewer's light or dark color preference. The standalone mark has no font

diff --git a/docs/assets/social/trace-social-preview.png b/docs/assets/social/trace-social-preview.png
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -10,7 +10,7 @@
     {% set social_title = config.site_name %}
   {% endif %}
   {% set social_description = page.meta.description if page and page.meta and page.meta.description else config.site_description %}
-  {% set social_image = "https://maveryn.github.io/trace/assets/paper-domain-montage/trace-paper-domain-montage.png" %}
+  {% set social_image = "https://maveryn.github.io/trace/assets/social/trace-social-preview.png" %}
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="{{ config.site_name | e }}">
   <meta property="og:title" content="{{ social_title | e }}">
@@ -19,12 +19,12 @@
     <meta property="og:url" content="{{ page.canonical_url | e }}">
   {% endif %}
   <meta property="og:image" content="{{ social_image }}">
-  <meta property="og:image:width" content="1512">
-  <meta property="og:image:height" content="780">
-  <meta property="og:image:alt" content="Examples from the eleven Trace visual domains and the Trace mark">
+  <meta property="og:image:width" content="1280">
+  <meta property="og:image:height" content="640">
+  <meta property="og:image:alt" content="Trace visual reasoning tasks and external benchmark transfer results">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="{{ social_title | e }}">
   <meta name="twitter:description" content="{{ social_description | e }}">
   <meta name="twitter:image" content="{{ social_image }}">
-  <meta name="twitter:image:alt" content="Examples from the eleven Trace visual domains and the Trace mark">
+  <meta name="twitter:image:alt" content="Trace visual reasoning tasks and external benchmark transfer results">
 {% endblock %}
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -115,6 +115,18 @@ pre {
   max-width: 48rem;
 }
 
+.trace-hero__evidence {
+  color: var(--trace-muted);
+  font-size: 0.84rem;
+  line-height: 1.6;
+  margin: 1.1rem auto 0;
+  max-width: 46rem;
+}
+
+.trace-hero__evidence strong {
+  color: var(--trace-teal-text);
+}
+
 .trace-resource-links {
   align-items: center;
   display: flex;

diff --git a/scripts/README.md b/scripts/README.md
@@ -36,6 +36,9 @@ The tools are:
 - `generate_release_gallery.py` regenerates the deterministic 11-domain
   gallery under `docs/assets/gallery/`, its hero montage, and the manifest at
   `docs/gallery/manifest.v1.json`.
+- `generate_social_preview.py` composes the `1280x640` repository and website
+  social preview from the committed Trace mark, domain montage, and verified
+  headline results.
 
 Scripts added here must use the `trace_tasks` namespace, accept
 repository-relative or user-supplied paths, avoid credentials and uploads, and

diff --git a/scripts/check_docs_site.py b/scripts/check_docs_site.py
@@ -15,10 +15,10 @@
 SITE_URL = "https://maveryn.github.io/trace/"
 SITE_PATH_PREFIX = "/trace"
 SOCIAL_IMAGE_URL = (
-    f"{SITE_URL}assets/paper-domain-montage/trace-paper-domain-montage.png"
+    f"{SITE_URL}assets/social/trace-social-preview.png"
 )
-SOCIAL_IMAGE_PATH = Path("assets/paper-domain-montage/trace-paper-domain-montage.png")
-SOCIAL_IMAGE_SIZE = (1512, 780)
+SOCIAL_IMAGE_PATH = Path("assets/social/trace-social-preview.png")
+SOCIAL_IMAGE_SIZE = (1280, 640)
 REQUIRED_PAGES = {Path("index.html"), Path("research/index.html")}
 NONCANONICAL_PAGES = {Path("404.html")}
 _SITE_PARTS = urlsplit(SITE_URL)