On this page
In one sentenceThe problem it fixesWhat changesWhat deliberately stays the sameWho should read whatForeground update-docs — Overview
PR #354 · ci(sandbox): foreground update-docs with live agent progress Changes one file: .github/workflows/sandbox-ops.yml (+9 / −4).
In one sentence
When someone manually refreshes a preview environment's AI documentation site, the GitHub Actions job now stays open and streams the docs agent's live progress, finishing exactly when the site is published — instead of firing off a detached background task and reporting "done" while the real work had barely started.
The problem it fixes
Every pull request in this repo gets a disposable sandbox — a full, seeded copy of the Dentolize app at https://<branch>.sandbox.anastawfik.com — plus an AI walkthrough site (docs just like this one) generated for it.
You can regenerate that walkthrough on demand from the Actions → Sandbox Ops → update-docs button. Before this PR, that button ran the docs agent detached (refresh --detach): the agent kept running in a background container, but the GitHub Actions job itself returned almost immediately. The result was the "job finished, but where are my docs?" problem — a green checkmark that meant "the agent was launched," not "the site is live." No live progress, no real success signal, and failures were invisible to the job.
What changes
| Aspect | Before | After |
|---|---|---|
update-docs execution | sandbox-docs … refresh --detach (fire-and-forget) | sandbox-docs … refresh (foreground) |
| Job log | Empty — agent runs elsewhere | Streams pages visited, files read, screenshots taken |
| Job success means | "agent was launched" | "site is published" |
timeout-minutes | 30 | 90 (covers deploying a missing sandbox first) |
| Runner capacity | One self-hosted slot | Second slot online so PR deploys aren't blocked* |
<small>*The second runner slot is described in the PR and the new code comment, but it is a homelab infrastructure change — it is not part of this diff. See For Quality.</small>
What deliberately stays the same
- PR-open auto-generation (in
sandbox.yml) still runs detached
(generate --detach). Nobody watches that job, so there is no benefit to holding a runner slot open for it.
- The other Sandbox Ops actions —
reseed,reset-data,redeploy,
destroy — are untouched; they already finished well within 30 minutes.
Who should read what
- For Marketing — the story: "watch your docs build, live."
- For Sales — how preview + auto-docs is a differentiator.
- For Support — what people will ask and how to answer.
- For Training — how to actually run
update-docs. - For Stakeholders — why it matters, cost, risk.
- For Quality — every edge and gap worth testing.
- Feature Tour — real screenshots of a live sandbox.
- In depth: The Sandbox Docs Pipeline ·
Foreground Execution & Runner Slots.
- Glossary — terms and the exact config that changed.
Pre-release note. This is an internal developer-experience change to the CI pipeline. It is not a customer-facing product feature and is not yet merged/released. Everything here describes what the code in the PR head actually does; where the PR description and the code disagree, this site documents the code and flags the gap.