For Training

A step-by-step for teaching an engineer to refresh a PR's AI walkthrough with the new foreground behavior — and to understand what they're seeing.

Prerequisites to teach

• The learner has repo access and can see the Actions tab.
• They understand a PR has a sandbox (a live seeded copy of the app) and a

docs site (an AI walkthrough). If not, teach The Sandbox Docs Pipeline first.

Lesson 1 — The mental model (2 minutes)

Draw this out:

PR opened ──► sandbox deployed ──► docs generated (auto, DETACHED, background)
                                         │
        (later, on demand) ─────────────┘
   Actions ▸ Sandbox Ops ▸ update-docs ──► docs refreshed (FOREGROUND, watch it live)

Key idea to land: auto-generation is fire-and-forget; the manual refresh you now watch live. This PR is only about that second arrow.

Lesson 2 — Run a refresh (the happy path)

1. Go to the Actions tab.
2. Select the Sandbox Ops workflow in the left sidebar.
3. Click Run workflow.
4. Pick the branch whose sandbox you want to refresh (ops are dispatched on

a branch ref, not a PR — this is the #1 thing people get wrong).

1. Set action = update-docs.
2. Click Run workflow.
3. Open the run. Watch the job step stream the agent's activity — pages

visited, files read, screenshots taken.

1. When the job goes green, the site is published. Open

https://<slug>.docs.anastawfik.com to see it.

Lesson 3 — What "done" means now (the whole point)

Contrast explicitly:

• Old behavior: green check = "we launched the agent." The site might not

exist yet. This caused the "job finished, but where are my docs?" confusion.

• New behavior: green check = "the site is published." The job stays

open for the entire agent run.

Have the learner say it back: "Green means live."

Lesson 4 — What you will NOT see

• No PR comment. update-docs doesn't post to the PR thread (unlike

reseed/redeploy/destroy). The evidence is the job log and the live site only.

• No speed-up. Same agent, same duration (~15–40 min; up to ~1h if it must

deploy a missing sandbox first). You're trading a fast-but-lying job for a slow-but-honest one.

Lesson 5 — Reading a run that goes wrong

Because the job is foreground, failures are now in the job. Teach the learner to:

1. Scroll to the last streamed action before the failure.
2. Check whether it died during deploy (missing sandbox) vs. **docs

generation**.

1. Note the elapsed time — near 90 min means it hit the timeout

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

Common mistakes checklist

• [ ] Ran on the wrong branch (Sandbox Ops is per-branch, not per-PR).
• [ ] Expected a PR comment — there isn't one for update-docs.
• [ ] Assumed faster — it's more visible, not faster.
• [ ] Confused auto-generation (detached, on PR open) with manual refresh

(foreground, on demand).

Instructor cheat-sheet (exact config)