Dentolize · Foreground update-docs Walkthrough
On this pageWho this affectsTop questionsQuick triage tableWhat NOT to tell people

For Support

"Support" here means helping engineers and reviewers who use the sandbox tooling — the internal audience for this CI change. Below are the questions that will actually come up and how to answer them.

Who this affects

Anyone who opens the Actions tab and runs Sandbox Ops → update-docs for a PR branch — typically the PR author, a reviewer, or whoever wants a fresh AI walkthrough of the changes.

Top questions

"I clicked update-docs. How long until the site is ready?"

The job now runs in the foreground, so the job itself finishing is the signal — when the Actions run goes green, the site is published. Typical run is ~15–40 minutes; it can reach ~1 hour if the sandbox for that branch doesn't exist yet and has to be deployed first. The job's timeout-minutes is 90 (.github/workflows/sandbox-ops.yml:48), so it will not be killed early.

"Where do I watch progress?"

Open the running job in the Actions tab. The step log now streams the agent's live activity — pages visited, files read, screenshots taken. This is the headline change: before, the log was empty because the agent ran detached.

"Where does the finished site live?"

At the branch's docs URL, pattern https://<slug>.docs.anastawfik.com (see .github/workflows/sandbox.yml:95). The refreshed site replaces the previous one.

"I ran update-docs but no PR comment appeared. Bug?"

Expected. Unlike reseed/redeploy/destroy, the update-docs action does not post or update the sandbox PR comment. Two guards make it skip:

  • the info capture step is skipped for update-docs

(.github/workflows/sandbox-ops.yml:67), and

  • the "Refresh sandbox comment" step has if: inputs.action != 'update-docs'

(.github/workflows/sandbox-ops.yml:72).

So the only place the docs run shows up is the Actions job log and the published site — not the PR thread. If someone expects a comment, that's the explanation.

"The docs on my PR appeared on their own — I never ran update-docs."

That's the PR-open auto-generation, a separate path in sandbox.yml that runs when the PR is first opened. It is still detached (generate --detach, .github/workflows/sandbox.yml:66), so its job returns fast and the site shows up ~15–40 min later. update-docs is the manual refresh for later.

"My update-docs run is taking forever / seems stuck."

  • Confirm it's actually running (streaming log lines) vs. queued waiting for a

runner.

  • Longest legitimate case (~1h) is when it must deploy a missing sandbox first.
  • Hard ceiling is 90 minutes — after that GitHub cancels the job.
  • If it fails, the failure is now visible in the job (that's the point) — read

the streamed log for the last action before it died.

"Did running docs block my PR's deploy?"

It shouldn't. A second runner slot was brought online so long foreground jobs (docs, QA) don't starve the quick PR deploys. If deploys do seem blocked, that's worth escalating — see For Quality, because the second slot lives in homelab infra, not in this repo.

Quick triage table

SymptomLikely causeAnswer
Green check, but site not updatedConfusing it with the old detached behaviorForeground now: green = published. Re-check the URL / hard refresh.
No PR comment after update-docsBy designupdate-docs never comments; check job log + site.
Job queued, not startingWaiting on a runner slotAnother job holds a slot; it starts when one frees.
Ran ~1 hourSandbox had to be deployed firstNormal for a branch with no existing sandbox.
Killed at 90 minHit timeout-minutesGenuinely stuck — capture the log and escalate.

What NOT to tell people

  • Don't tell them it's faster — it isn't; it's observable.
  • Don't tell them to expect a PR comment from update-docs — it doesn't post one.