DaoyuanLi2816 · DaoyuanLi2816 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -2,38 +2,92 @@ name: docs
 
 on:
   workflow_dispatch:
+  pull_request:
+    branches: [main]
   push:
     branches: [main]
-    paths:
-      - "docs/**"
-      - "mkdocs.yml"
-      - ".github/workflows/docs.yml"
+    tags: ["v*"]
 
 permissions:
   contents: read
   pages: write
   id-token: write
 
 concurrency:
-  group: pages
+  group: docs-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
+  visual:
+    name: strict build and browser visual gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install pinned docs dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Verify generated documentation artifacts
+        run: |
+          python scripts/publish_alignment_lab_artifacts.py --check
+          python scripts/publish_verl_bridge_diagrams.py --check
+      - name: Build complete development site strictly
+        run: mkdocs build --strict
+      - name: Install deterministic Chromium
+        run: playwright install --with-deps chromium
+      - name: Inspect four documentation viewports
+        run: python scripts/check_docs_visual.py --site site --screenshots docs-visual-screenshots
+      - name: Upload browser screenshots
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docs-visual-screenshots
+          path: docs-visual-screenshots
+          if-no-files-found: error
+
   build:
+    name: build stable root and development subsite
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    needs: visual
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
           cache: pip
       - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b
-      - run: python -m pip install "mkdocs>=1.6,<2"
-      - run: mkdocs build
+      - name: Install pinned docs dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Build current development docs strictly
+        run: mkdocs build --strict --site-dir "${RUNNER_TEMP}/dev-site"
+      - name: Build the latest immutable release at the site root
+        shell: bash
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            stable_tag="${GITHUB_REF_NAME}"
+          else
+            stable_tag="$(git tag --list 'v*' --sort=-v:refname | head -n 1)"
+          fi
+          test -n "$stable_tag"
+          git worktree add --detach "${RUNNER_TEMP}/stable-checkout" "$stable_tag"
+          (
+            cd "${RUNNER_TEMP}/stable-checkout"
+            mkdocs build --strict --site-dir "${GITHUB_WORKSPACE}/site"
+          )
+          mkdir -p "${GITHUB_WORKSPACE}/site/dev"
+          cp -a "${RUNNER_TEMP}/dev-site/." "${GITHUB_WORKSPACE}/site/dev/"
       - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b
         with:
           path: site
+
   deploy:
+    name: deploy versioned documentation
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,11 +6,52 @@ All notable changes to miniVERL are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-08-03
+
+### Added
+
+- Deterministic real-browser documentation gates across five representative
+  pages and four viewports, with overflow, SVG bounds, label collision,
+  readability, table and responsive-bridge assertions plus screenshot
+  artifacts.
+- Responsive desktop and mobile bridge diagrams that separate the verified
+  local runtime, portable bundle and pinned upstream smoke from explicitly
+  untested distributed execution.
+
+### Changed
+
+- The Alignment Lab case study now uses three data-bound forest/matrix figures
+  that show every measured seed, preserve not-applicable query ratios and make
+  the limited sandbox-safety coverage explicit without changing frozen data.
+- The documentation uses pinned Material 9.7.7 with stable/development paths,
+  search, dark/light modes, copy controls and a task-oriented landing page.
+- The English and Chinese READMEs are shorter product guides with one scoped
+  evidence summary and direct Align, Distill locally and Scale out paths.
+
+### Fixed
+
+- `import-verl` now classifies field semantics, fails closed with a
+  non-executable template when data, teacher, objective or schedule choices are
+  unresolved, accepts finite scientific-notation strings and validates every
+  runnable recipe before atomic publication.
+- `export-verl` now reports artifact completeness, upstream parse/load smoke,
+  reward implementation, launchability, distributed execution and algorithm
+  parity independently; its fail-closed scaffold emits `launch.template.sh`
+  and is never described as ready to launch.
+
+### Verified
+
+- Official verl `v0.8.0` commit `7aed6b230776f963fa09509c10d9c3a767d1102c`
+  still passes the bounded parse/load smoke. Distributed execution and
+  miniVERL OPD-to-PPO semantic parity remain untested and unclaimed.
+- Every frozen calculator, RecoveryBench, Consumer Runtime, Alignment Lab and
+  bridge-smoke JSON/JSONL artifact remains byte-identical.
+
 ## [0.6.0] - 2026-08-03
 
 ### Added
 
-- A compatibility Level-3 bridge for the fail-closed
+- A miniVERL-defined compatibility Level-3 bridge for the fail-closed
   `single-gpu-online-distillation-v1` profile, pinned to official verl `v0.8.0`
   commit `7aed6b230776f963fa09509c10d9c3a767d1102c`.
 - `import-verl`, bidirectional prompt-Parquet conversion, `export-verl` standard
@@ -556,7 +597,8 @@ Same-tokenizer only; one trajectory per forward pass; `swap` unavailable for
 quantized models; only Qwen3 and Qwen2 architectures tested; single-seed GPU
 results. The full list is in `docs/limitations.md`.
 
-[Unreleased]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.3.0...v0.4.0

diff --git a/CITATION.cff b/CITATION.cff
@@ -2,7 +2,7 @@ cff-version: 1.2.0
 title: "miniVERL: On-policy distillation for tool-using agents on one GPU"
 message: "If you use miniVERL in your work, please cite it as below."
 type: software
-version: 0.6.0
+version: 0.6.1
 date-released: 2026-08-03
 license: Apache-2.0
 repository-code: "https://github.com/DaoyuanLi2816/mini-verl"
@@ -98,4 +98,4 @@ references:
     url: "https://arxiv.org/abs/2603.07079"
     notes: >-
       Motivates recording per-token teacher entropy. Entropy-aware divergence
-      mixing is a roadmap item and is not implemented in miniVERL v0.6.0.
+      mixing is a roadmap item and is not implemented in miniVERL v0.6.1.
diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md
@@ -6,12 +6,27 @@ and what it printed.
 
 Last updated: 2026-08-03.
 
+## v0.6.1 Visual integrity and bridge correctness release candidate
+
+| item | current state |
+| --- | --- |
+| scope | representation and documentation UX were rebuilt without rerunning a benchmark; import/export bridge semantics now fail closed instead of implying runnable or equivalent execution |
+| Alignment Lab visuals | the four non-data-bound scatterplots are replaced by a three-seed delta forest, an outcome/cost matrix and a metric-coverage matrix; not-applicable teacher ratios remain N/A, and the zero-variance sandbox checks are not plotted as a two-dimensional safety result |
+| bridge diagram | responsive desktop/mobile layouts show solid arrows only across the verified local runtime, portable bundle and pinned `v0.8.0` / `7aed6b23` parse-load smoke, followed by a dashed arrow to prominent `Distributed execution: NOT TESTED` |
+| import contract | every source field is classified as exact, derived, informational only, requiring user confirmation or unsupported; unresolved data/environment, teacher, objective or schedule semantics produce `needs_user_input` plus a non-executable template |
+| export status | artifact completeness, upstream parse/load, model/data smoke, reward implementation, launchability, distributed testing and algorithm parity are independent flags; the fail-closed reward scaffold remains non-launchable and uses `launch.template.sh` |
+| documentation | pinned Material 9.7.7 supplies stable/dev navigation, search, dark/light modes, command-copy controls and responsive tables/images; the landing page exposes Align, Distill locally and Scale out paths |
+| visual gate | Playwright checks five pages at 1440x900, 1024x768, 820x1000 and 390x844 for overflow, SVG bounds, label collisions, readable labels, tables and the responsive bridge; docs run [`30855762827`](https://github.com/DaoyuanLi2816/mini-verl/actions/runs/30855762827) is green and its 20 Linux screenshots were manually inspected |
+| validation | local ruff, format, mypy, actionlint, full non-GPU/non-network, available GPU/network, strict MkDocs, browser visual, package/Twine, clean-install, extracted-sdist, bridge end-to-end, privacy, Markdown/link and generated-byte gates pass; PR-head CI [`30855762617`](https://github.com/DaoyuanLi2816/mini-verl/actions/runs/30855762617), build [`30855763132`](https://github.com/DaoyuanLi2816/mini-verl/actions/runs/30855763132) and pinned bridge [`30855762724`](https://github.com/DaoyuanLi2816/mini-verl/actions/runs/30855762724) are green |
+| immutable evidence | no result JSON/JSONL or frozen bridge-smoke record changed; calculator SHA-256 remains `53fc1d4d5b7adee09618d77ad62d4086ba56b78569832d6fc7c3bcd5c2695bbc` and Alignment Lab result/task SHA-256 values remain `584752dccb91654109c357b8ebb12681a12a9c1476a9ba539dd35e4d860a22ef` / `8d7fc723436d7377d196fc44046d960e3cb7f0aa81e03d49ef05b627eb84630f` |
+| release state | exact `0.6.1` metadata is being finalized on focused PR [#40](https://github.com/DaoyuanLi2816/mini-verl/pull/40); merge, tag and OIDC publication remain gated on the final head being green |
+
 ## v0.6.0 Verified verl Bridge release
 
 | item | current state |
 | --- | --- |
 | audited upstream | official stable verl `v0.8.0`, source commit `7aed6b230776f963fa09509c10d9c3a767d1102c`, tested with Python 3.12; the installed source reports `0.8.0.dev0` |
-| compatibility contract | Levels 0-3 are explicit; Level 2 is a fail-closed 14-field whitelist for `single-gpu-online-distillation-v1`; Level 3 exchanges standard HF/PEFT/safetensors/tokenizer/Parquet artifacts and a checksummed scale-out bundle |
+| compatibility contract | Levels 0-3 are explicitly miniVERL-defined; Level 2 is a fail-closed 14-field whitelist for `single-gpu-online-distillation-v1`; miniVERL-defined Level 3 exchanges standard HF/PEFT/safetensors/tokenizer/Parquet artifacts and a checksummed scale-out bundle |
 | command surface | `import-verl`, `convert-dataset`, `export-verl`, `bridge doctor` and `benchmark --export-community` are implemented without importing torch in the core path |
 | exact compatibility smoke | the pinned source installed successfully; OmegaConf parsed official and exported config shapes; PEFT, safetensors, train/val Parquet, reward import, privacy and all bundle hashes passed; the checksummed record is `docs/generated/verl-bridge-smoke.json` |
 | distributed boundary | Ray, FSDP/Megatron, vLLM/SGLang and a full distributed run were not installed or launched; distributed execution remains explicitly `not tested` |