Feature Tour (screenshots)

What you can — and can't — screenshot here

Be honest about this up front: the feature in this PR is a GitHub Actions execution-mode change. It has no product UI. The things it actually touches — the "Run workflow" dispatch form, the streaming job log, the published docs site — live in the GitHub Actions interface, which this walkthrough builder cannot reach from the sandbox.

So this tour does the honest thing instead: it shows the real artifact the pipeline exists to protect and keep unblocked — a live, fully-seeded PR sandbox — captured from this branch's actual environment at https://ci-ops-foreground-docs.sandbox.anastawfik.com. Every screenshot below is a real screen from that running sandbox. The workflow mechanics themselves are drawn as annotated diagrams, since there's no honest screenshot for them.

1. The sandbox's front door

This is the login screen of the preview environment stood up for this very branch. The update-docs action refreshes the AI walkthrough for a sandbox like this one; the second runner slot exists so deploying sandboxes like this never gets blocked by a long docs job.

The seed roster (from sandbox-info.env) lets you sign in as owner, doctor1, receptionist1, and others — all sharing one password. We used Login with username (sandbox / owner) to enter.

2. A live, richly-seeded clinic

After login: the Sandbox Dental dashboard, titled "Owner · All Permissions." This is what "a sandbox" concretely means — a complete Dentolize clinic with real appointments, invoices, patients, and payments seeded in (SEED_MODE=rich).

Why this matters to this PR: standing up an environment this complete is the work the CI runner does on every PR. A foreground docs job holds a runner slot for up to an hour — which is exactly why a second slot had to come online so deploys of environments like this keep flowing.

3. The depth behind each preview

The Analytics hub — Reports, Salaries, Income Statement, Doctors, Invoices, Payments, and more — over a July 2026 date range for "Riyadh Clinic." It's a reminder that each per-PR sandbox is a full app, not a stub. Generating an accurate AI walkthrough of a change against something this rich is why the docs agent takes 15–40 minutes — and why watching it live (this PR's whole point) is worth the held runner slot.

4. The part that changed — drawn, not screenshotted

Since the actual change is invisible in the product, here is the honest picture of it. Before (detached):

Actions ▸ Sandbox Ops ▸ update-docs
   └─ job: sandbox-docs … refresh --detach
        └─ launches agent in background container ──► job EXITS (green) in seconds
             (agent keeps running, unseen) ……… site appears later, or fails silently
   Result: ✅ "done" — but docs not actually ready.  "job finished, but where are my docs?"

After (foreground — this PR):

Actions ▸ Sandbox Ops ▸ update-docs
   └─ job: sandbox-docs … refresh          (no --detach)
        └─ agent runs INSIDE the job ──► streams: pages visited, files read, screenshots taken
             └─ job stays open the whole time (timeout 90 min)
                  └─ job turns green ONLY when the site is published
   Result: ✅ "done" = site is live.  Failures show up in the job log.

The entire diff that produces this behavior change:

-    timeout-minutes: 30
+    timeout-minutes: 90
...
-            update-docs) /opt/homelab/sandbox/bin/sandbox-docs dentolize "${{ github.ref_name }}" refresh --detach ;;
+            update-docs) /opt/homelab/sandbox/bin/sandbox-docs dentolize "${{ github.ref_name }}" refresh ;;

See it in context at .github/workflows/sandbox-ops.yml:48 and .github/workflows/sandbox-ops.yml:65, and read the full mechanics in Foreground Execution & Runner Slots.

Capture notes (for honesty)

• Environment: ci-ops-foreground-docs.sandbox.anastawfik.com, commit

7687f8d, SEED_MODE=rich.

• Login used: username owner, company sandbox.
• Not shown: the GitHub Actions dispatch form, streaming job log, and the

rendered docs site — no honest screenshot of those is reachable from here, so they're represented as diagrams above rather than faked.