Dentolize · AI-Gated UI Screenshot Tour Walkthrough
On this pageWhat this isWhy it mattersWhat's actually in this repositoryScope: web vs. mobileStatus

Overview

PR #420 — ci(sandbox): AI-gated UI screenshot tour on every deploy Branch: ci/sandbox-ui-screenshot-tour → main

What this is

This PR does not change anything a dentist, receptionist, or patient will ever see in Dentolize. It changes how pull requests get reviewed.

Today, when an engineer opens a PR that changes a screen in the clinic web app or the mobile app, a reviewer has to either read the code and imagine what it looks like, or manually deploy the sandbox and click through it themselves. This PR adds a new step to the existing Sandbox deploy workflow that does that legwork automatically: after every deploy, an AI agent looks at what the PR changed, decides which screens are worth showing, drives the live PR sandbox to those screens with a browser, takes screenshots, and posts them as a single, self-updating comment on the PR — titled 📸 UI changes.

Why it matters

  • Faster reviews. A reviewer can see the actual rendered screen in the

PR comment instead of re-deploying a sandbox and clicking through it by hand.

  • No cost on backend-only PRs. A cheap, deterministic check runs first

and exits immediately if the diff doesn't touch packages/clinic-web/ or packages/clinic-mobile/ — no AI agent is ever started for a resolver/schema/migration-only PR.

  • Doesn't block the runner. Like the existing branch-docs step it sits

next to, it runs detached: the workflow step kicks it off and moves on, so the single self-hosted runner slot is free for the next job while the screenshot agent keeps working in the background.

What's actually in this repository

This is a small, surgical PR: 12 lines added to one file, .github/workflows/sandbox.yml — see the Feature breakdown page for the exact diff and line numbers. It adds one new step to the existing deploy job that invokes a host-side orchestrator, sandbox-shots.

The orchestrator itself — the gate logic, the AI agent prompt, and the code that builds/updates the PR comment — is intentionally not part of this repository. Per the PR description, it lives under /opt/homelab/sandbox on the CI runner host, alongside the sibling sandbox, sandbox-docs, and sandbox-ops tools this workflow already calls the same way. That means this documentation can verify and cite exactly one thing precisely: the workflow wiring. Everything about the gate's exact logic, the agent's exact prompt, and the comment's exact formatting is described here as claimed by the PR author, clearly flagged as such, because the code that would prove it isn't in /work/repo to read.

Scope: web vs. mobile

  • clinic-web is fully wired. The sandbox serves a normal web build the

agent's browser can just navigate to.

  • clinic-mobile is best-effort and off by default, gated behind an

(unverified, host-side) SHOTS_MOBILE flag. The mobile app's API host is hardcoded per build type in packages/clinic-mobile/src/utils/variables.js:13 (BACKEND_URL) with no environment-variable override, so an Expo-web build can't easily be pointed at a given PR's sandbox API. This is a real, verifiable constraint in this repo — see the Feature breakdown page.

Status

Unreleased. This documents the workflow change as it exists on this PR's branch; it has not yet merged to main.