Run documentation browser checks on demand through an agent skill

.agents/skills/docs-visual-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: docs-visual-review
+description: Review the OpenShell Research documentation site's rendering and interactions using the existing browser layout suite and screenshots. Use for visual regressions, Dev Notes typography or hero changes, shared CSS or navigation changes, or a requested visual audit; routine documentation edits do not require it.
+---
+
+# Documentation visual review
+
+Run commands from the OpenShell Research repository root. Read
+`docs/development/index.md` and applicable `AGENTS.md` instructions first.
+Browser validation is on demand, not a CI gate. Preserve the ordinary renderer,
+JavaScript, and clean-build checks; do not add browser runs back to CI.
+
+## Choose the scope
+
+Use `tests/test_dev_notes_layout.py` and its adjacent uv lock rather than writing
+another browser harness. It discovers current Dev Notes and covers Chromium and
+WebKit, light (`default`) and dark (`slate`) themes, and desktop, tablet, and phone
+viewports. Start with tests relevant to the change. Run the full suite when
+changing shared layout or when the user requests a comprehensive review.
+
+Examples of focused selections with pytest's `-k`:
+
+- Index hierarchy, title, subtitle, featured card: `index_reading_proportions`.
+- Hero or card changes: `post_reading_proportions or featured_image_also_works_as_a_thumbnail`.
+- Filters, author links, history, no-JavaScript fallback: `filters or bylines or without_javascript`.
+- Breadcrumbs, footer, mobile drawer, tables: `shared_documentation_navigation`.
+- Embedded recordings: `embedded_video_playback`.
+
+For a single note, use `--collect-only -q` to find its parametrized test IDs,
+then select the relevant filename with `-k`. Keep both browsers, themes, and
+screen sizes for final validation of affected surfaces. A quick single-browser
+run is useful during iteration but does not establish cross-browser correctness.
+
+## Build and run
+
+Build the current sources before testing; browser tests read `site/` and do not
+rebuild it:
+
+```sh
+scripts/build-docs.sh
+```
+
+Install browsers once per environment, or again if the locked Playwright version
+changes. This installs Chromium, WebKit, and their system dependencies:
+
+```sh
+uv run --locked --script tests/test_dev_notes_layout.py --install-browser
+```
+
+For example, check the index across the browser/theme/viewport matrix:
+
+```sh
+uv run --locked --script tests/test_dev_notes_layout.py -q -k index_reading_proportions
+```
+
+For a comprehensive review:
+
+```sh
+uv run --locked --script tests/test_dev_notes_layout.py -q
+```
+
+The full suite can take about six minutes. It starts and stops its own local HTTP
+server. Screenshots from page-fixture tests are saved to
+`.cache/dev-notes-layout/`, with test and parameter names in the filenames.
+Inspect files produced by the current run; other screenshots may be stale.
+External requests are blocked for deterministic checks, so separately inspect
+external avatars or embeds when those are relevant to the task.
+
+## Inspect the rendered result
+
+Open the relevant screenshots with an available image-viewing tool. Passing
+geometry assertions does not establish visual quality or diagram-label
+readability. For a visual audit, also serve the complete built site and interact
+with the affected pages in an available browser:
+
+```sh
+python3 -m http.server 8000 --directory site
+```
+
+Reuse an existing artifact preview when available. On a remote machine,
+localhost alone is not a user-accessible preview; report a verified forwarded or
+published preview URL if the user needs to view it.
+
+Judge the result against these established design decisions:
+
+- The Dev Notes masthead has a prominent serif title and readable subtitle with
+  breathing room. Divider lines separate filters from the introduction and
+  posts. The featured note is larger than archive entries; the archive scrolls
+  naturally rather than shrinking or acquiring its own scroll panel.
+- Article titles, subtitles, and complete heroes fit the opening viewport using
+  shared styles. Heroes preserve their proportions without cropping, stretching,
+  overflowing figures, or overlapping the byline. Inspect both theme variants
+  and the full-size asset for detailed diagrams. Author thumbnails stay left;
+  sidebar post links contain titles only.
+- Text columns remain readable, phones have no page-wide horizontal overflow,
+  tables scroll within the article, and navigation labels do not clip or overlap.
+- Exercise category and author combinations, empty results, clear filters,
+  refresh, Back/Forward, and byline links when filtering changes. Check mobile
+  navigation and video playback when those surfaces change.
+
+Fix shared styles, templates, or source metadata rather than hand-editing
+renderer-owned HTML or adding per-post sizing overrides. Rebuild after changes
+and rerun affected checks. Do not weaken assertions solely to silence failures;
+update a constraint only when the requested design has intentionally changed.
+
+Report the tested pages and scope, browser results, screenshots inspected, and
+any unverified surfaces or blocked checks. Do not claim a visual review based
+only on passing tests or test collection.

.github/workflows/docs.yml

@@ -66,25 +66,6 @@ jobs:
       - name: Build documentation
         run: scripts/build-docs.sh
 
-      - name: Set up uv for browser checks
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
-
-      - name: Install layout-check browser
-        run: uv run --locked --script tests/test_dev_notes_layout.py --install-browser
-
-      - name: Check Dev Notes reading layouts
-        run: uv run --locked --script tests/test_dev_notes_layout.py -q
-
-      - name: Upload Dev Notes layout screenshots
-        if: always()
-        uses: actions/upload-artifact@v7
-        with:
-          name: dev-notes-layout
-          path: .cache/dev-notes-layout
-          include-hidden-files: true
-          if-no-files-found: ignore
-          retention-days: 7
-
       - name: Verify generated documentation is committed
         run: git diff --exit-code -- docs/dev-notes zensical.toml
 

docs/dev-notes/AGENTS.md

@@ -20,7 +20,7 @@ optional subtitle and hero, author byline, index cards, and navigation.
 - Keep typography and hero sizing in the shared Dev Notes stylesheet. Do not add
   per-post title or hero sizing rules, inline styles, or fixed aspect ratios.
 - Keep detailed body figures readable; the hero links to its full-size image.
-- Run the documented build and locked browser layout checks. They discover all
-  notes automatically and cover both themes, desktop and phone widths, and a
-  featured note moving into the recent list. Commit regenerated files with the
-  authored metadata.
+- Run the documented renderer tests and build. Commit regenerated files with
+  the authored metadata. For rendering problems or presentation changes, use
+  `.agents/skills/docs-visual-review/SKILL.md` from the repository root for
+  on-demand browser checks and screenshot inspection; they are not CI gates.

docs/development/index.md

@@ -159,26 +159,15 @@ python3 scripts/render-dev-notes.py
 
 Commit any generated changes with the source change.
 
-The Docs workflow runs the header tests, verifies generated content is committed,
-and checks the built site in Chromium and WebKit at desktop, tablet, and phone
-sizes in both themes. The browser checks discover every note automatically. They reject missing
-hero assets or alt text, cropped or thumbnail-sized article heroes, overly long text lines,
-horizontal page overflow, off-center heroes, images overflowing their figures or
-overlapping the byline, incorrect theme-image visibility, an opening that needs
-scrolling to see the full hero, and an index that obscures the featured title on
-laptops or pushes the featured note below a 900px-tall
-desktop viewport. They also check the separation of introduction, filters, and posts.
-They also move the featured note into the recent list to exercise its thumbnail
-layout. The workflow saves screenshots as the `dev-notes-layout` artifact for
-visual review. These are layout
-constraints rather than pixel snapshots, so ordinary prose edits need no new
-baselines. They cannot judge the readability of labels baked into an image;
-review the screenshot and full-size image for detailed charts.
-
-The same browser checks cover shared navigation: footer titles must fit inside
-their links, breadcrumbs must remain readable, and wide documentation tables
-must scroll within the article without overflowing the page.
-Embedded demos are also played in both browsers. Publish MP4 recordings with
+The Docs workflow runs renderer and header tests, JavaScript checks, the clean
+site build, and verification that generated content is committed. Browser layout
+checks run on demand, outside CI. Coding agents should use the repository's
+[docs-visual-review skill](https://github.com/NVIDIA/OpenShell-Research/blob/main/.agents/skills/docs-visual-review/SKILL.md)
+when investigating rendering problems, changing shared presentation, or reviewing
+the site's appearance. It describes focused and full Chromium/WebKit checks,
+interaction testing, and screenshot review.
+
+Publish MP4 recordings with
 H.264 video, 8-bit `yuv420p` pixels, and streaming metadata at the beginning of
 the file (`faststart`); HEVC-only recordings do not play in every browser.
 
@@ -216,14 +205,11 @@ uv run --python 3.12 --with pytest==8.4.2 pytest -q \
 node --check docs/javascripts/pi-traces.js
 node tests/docs-preview.test.js
 scripts/build-docs.sh
-uv run --locked --script tests/test_dev_notes_layout.py --install-browser
-uv run --locked --script tests/test_dev_notes_layout.py -q
 ```
 
-The browser installer is needed once per environment. The test script's inline
-dependencies and adjacent uv lock pin its toolchain independently of the site
-builder. Browser checks serve the built artifact on an ephemeral local port and
-write viewport screenshots to `.cache/dev-notes-layout/`.
+For optional browser validation, follow the `docs-visual-review` skill linked
+above. Its locked test runner serves the built artifact on an ephemeral local
+port and writes screenshots to `.cache/dev-notes-layout/` for local inspection.
 
 `scripts/build-docs.sh` recreates `.venv-docs`, installs the pinned toolchain,
 stages each configured canonical project documentation tree from `projects/`