Dentolize · Foreground update-docs Walkthrough
On this pageTermsThe exact config that changed (PR #354)Key file:line referencesNot in this repository (verify externally)Related reading

Glossary & Config Notes

Terms

Sandbox — A disposable, fully-seeded, running copy of Dentolize created per PR branch at https://<branch>.sandbox.anastawfik.com. Stood up by the sandbox CLI on the homelab runner. Torn down when the PR closes.

Docs site / AI walkthrough — An audience-first documentation site (like this one) generated by an AI docs agent for a PR's changes, published at https://<slug>.docs.anastawfik.com.

Docs agent — Headless Claude Code that reads the PR, drives the sandbox to capture real screenshots, and writes the walkthrough. Invoked via the sandbox-docs CLI.

generate vs. refresh — The two sandbox-docs verbs. generate builds docs on PR open (detached); refresh rebuilds them on demand via the update-docs action (foreground after this PR).

Detached execution — A CI job launches a background task and exits immediately. Fast green check, but "done" only means "launched." Achieved here with the --detach flag.

Foreground execution — The CI job runs the work inside itself and stays open until it finishes. "Done" means done; progress is streamed live. This PR removes --detach from update-docs to get this.

Runner slot — One concurrent job capacity on a self-hosted GitHub Actions runner. A slot runs one job at a time. Adding a second slot lets a long foreground job run without blocking quick PR deploys.

Self-hosted runner — The homelab machine that executes these workflows, selected by the label set [self-hosted, homelab, dentolize].

workflow_dispatch — The manual "Run workflow" trigger. Sandbox Ops and Sandbox QA use it; you pick the branch (a git ref, not a PR) to operate on.

Concurrency group — A key that serializes runs sharing it. cancel-in-progress decides whether a new run cancels an in-flight one. For update-docs it's false (a repeat dispatch queues, never cancels).

Sandbox Ops — The sandbox-ops.yml workflow: manual per-branch actions reseed, reset-data, redeploy, destroy, update-docs.

Sandbox QA — The sandbox-qa.yml workflow: an AI QA agent (review/plan/test/fix/full-auto); the other long-running foreground job the second runner slot accommodates.

The exact config that changed (PR #354)

File: .github/workflows/sandbox-ops.yml — the only file in the PR.

SettingBeforeAfterLine
timeout-minutes3090:47
update-docs commandsandbox-docs … refresh --detachsandbox-docs … refresh:65
Surrounding comments"Detached — outlives this job (single runner slot)""Foreground — streams live activity; second slot keeps deploys unblocked":45–47, :62–64

Key file:line references

WhatLocation
update-docs foreground command.github/workflows/sandbox-ops.yml:65
Raised timeout.github/workflows/sandbox-ops.yml:48
Action choices (incl. update-docs).github/workflows/sandbox-ops.yml:30
Concurrency (cancel-in-progress: false).github/workflows/sandbox-ops.yml:34–36
Runner label set.github/workflows/sandbox-ops.yml:44
Info-capture skip for update-docs.github/workflows/sandbox-ops.yml:67
Comment-step skip for update-docs.github/workflows/sandbox-ops.yml:72
Auto-generate (detached, PR open).github/workflows/sandbox.yml:66
Auto-generate open-only guard.github/workflows/sandbox.yml:59
Docs URL announcement.github/workflows/sandbox.yml:95
Deploy concurrency (cancel-in-progress: true).github/workflows/sandbox.yml:26–27
Stale "single-slot" comment (drift).github/workflows/sandbox-qa.yml:18–19
QA timeout (300).github/workflows/sandbox-qa.yml:58

Not in this repository (verify externally)

  • The sandbox and sandbox-docs CLIs at /opt/homelab/sandbox/bin/ —

their internals (including refresh deploying a missing sandbox) can't be read from source here.

  • The second runner slot — homelab runner configuration; the safety of

foregrounding depends on it being online. See For Quality, Gap 1.