@@ -48,6 +48,24 @@
       .patch-columns > .patch-destinations { flex: none; max-width: none; overflow-y: visible; }
     }
     .components-dropdown-menu__toggle { display: flex; flex-direction: row-reverse; gap: 4px; }
+    /*
+      The cue that points a contributor at the next thing to do (#252). The
+      render puts `.next-action-cue` on exactly one block — whichever the
+      resolver named — and the cue hook scrolls it into view. A soft amber glow
+      marks it: subtle, no motion, and it sits over the block's own background
+      rather than replacing it, so a coloured banner (the red "update
+      incomplete", say) keeps its meaning. The block's own status text names the
+      step, so the glow carries no label. No animation, so nothing here needs a
+      reduced-motion guard; the only movement is the scroll, gated in the hook.
+
+      `border-radius` here only rounds the glow around the wrapped action
+      buttons, which set none of their own. The blocks set their radius inline,
+      which the glow follows and this does not override.
+    */
+    .next-action-cue {
+      border-radius: 10px;
+      box-shadow: 0 0 0 3px rgba(240, 184, 73, 0.45), 0 0 14px 3px rgba(240, 184, 73, 0.30);
+    }
   </style>
   <link rel="stylesheet" href="index.css" />
   <script defer src="index.js"></script>
 
@@ -21,6 +21,7 @@ import '@wordpress/components/build-style/style.css';
 import { Terminal } from 'xterm';
 import 'xterm/css/xterm.css';
 import { computeSetupStepState } from './setup-steps.cjs';
+import { deriveNextAction } from './next-action.cjs';
 import { shouldShowTerminalHints, computeTerminalBusy } from './terminal-hints.cjs';
 import { planDevServerStart, formatElapsed } from './dev-server-command.cjs';
 import { appendBounded, countLines } from './debug-log.cjs';
@@ -201,6 +202,34 @@ function useContributorProvenance() {
   return { handle, event, rememberHandle, rememberEvent };
 }
 
+// Brings the block the contributor should act on next into view when it changes,
+// so their one hint is never left below the fold (#252). The mark itself is
+// drawn by React — the `.next-action-cue` class the render binds to this same id
+// — because a className survives re-render where an imperative one would be
+// reconciled away; this handles only the movement, which no className can do.
+//
+// Gated on `isActive` because every SiteRow stays mounted at once: without it a
+// background site could yank the viewport the moment its own state changed. It
+// fires on a *change* of the id (or on becoming active), not on every render, so
+// a contributor reading one block is not dragged off it by an unrelated update.
+function useNextActionCue(nextActionId, isActive, containerRef) {
+  useEffect(() => {
+    if (!isActive || !nextActionId) return;
+    const root = containerRef.current;
+    if (!root) return;
+    const el = root.querySelector(`[data-next-action="${nextActionId}"]`);
+    if (!el) return;
+    // `center` brings the block clearly into view rather than just nudging it to
+    // the nearest edge — the cue only fires when the target *changes*, so this
+    // moves the viewport to whatever is newly worth looking at (a step that just
+    // became current, an operation that just started) without fighting a
+    // contributor mid-read. Reduced motion drops the smooth glide to an instant
+    // jump.
+    const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    el.scrollIntoView({ block: 'center', behavior: reduceMotion ? 'auto' : 'smooth' });
+  }, [nextActionId, isActive, containerRef]);
+}
+
 // The two halves are one piece of state because one change moves both: adopting
 // the directory the app really created has to retire the guessed row and carry
 // its metadata across, and two setters cannot do that without a render in
@@ -1728,6 +1757,9 @@ function SiteRow({ sitePath, initialized, createdAt, label, onInitialized, onSit
 
   // terminal refs/state (after run helpers so dependencies are available)
   const terminalContainerRef = useRef(null);
+  // The scroll root for the next-action cue (#252): the whole detail section, so
+  // the cue can find whichever block is the next step wherever it sits.
+  const nextActionSectionRef = useRef(null);
   const terminalRef = useRef(null);
   const terminalStickRef = useRef(true);
   const terminalInputHandlerRef = useRef(() => {});
@@ -3470,8 +3502,27 @@ function SiteRow({ sitePath, initialized, createdAt, label, onInitialized, onSit
     return { ...step, status };
   });
 
+  // The one block to point the contributor at next (#252). The checklist has
+  // already worked out its own current step; the resolver folds that together
+  // with the post-init state into a single id, which the render tags onto the
+  // matching block (`data-next-action` + the `.next-action-cue` class) and the
+  // cue hook scrolls into view.
+  const currentSetupStep = stepItems.find((s) => s.status === 'current')?.key || null;
+  const nextAction = deriveNextAction({
+    skipInit,
+    currentSetupStep,
+    updateIncomplete,
+    isUpdating,
+    stale: age.stale,
+    running,
+    hasChanges: Boolean(worktreeDirty && worktreeDirty.dirty),
+    ticketLinked: Boolean(tracTicket)
+  });
+  const nextActionId = nextAction ? nextAction.id : null;
+  useNextActionCue(nextActionId, isActive, nextActionSectionRef);
+
   return (
-    <section style={{ display: 'flex', flexDirection: 'column', gap: 24, paddingBottom: 48 }}>
+    <section ref={nextActionSectionRef} style={{ display: 'flex', flexDirection: 'column', gap: 24, paddingBottom: 48 }}>
       <Flex align="flex-start" justify="space-between" style={{ gap: 16, flexWrap: 'wrap' }}>
         <div style={{ flex: '1 1 440px', minWidth: 0 }}>
           <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
@@ -3687,9 +3738,12 @@ function SiteRow({ sitePath, initialized, createdAt, label, onInitialized, onSit
           <div style={{ marginTop: 16, display: 'flex', flexDirection: 'column', gap: 12 }}>
             {stepItems.map((step) => {
               const visuals = checklistVisuals[step.status] || checklistVisuals.locked;
+              const cueId = `setup-${step.key}`;
               return (
                 <div
                   key={step.key}
+                  data-next-action={cueId}
+                  className={nextActionId === cueId ? 'next-action-cue' : undefined}
                   style={{
                     border: `1px solid ${visuals.border}`,
                     background: visuals.background,
 
@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Decides the one thing the contributor should do next, anywhere in a site's
+ * detail view.
+ *
+ * The view is a stack of panels — a setup checklist, then (once the wizard is
+ * skipped) banners for an incomplete or stale update, a dev-server bar, a
+ * ticket panel, a patch panel. Each panel already knows whether it has
+ * something to offer, but nothing looked across them to say which one is *the*
+ * next step. A contributor lands on the screen and the relevant control may be
+ * scrolled out of view, or sit among several with nothing to say "start here"
+ * (#252).
+ *
+ * This is that decision, and only the decision. It returns the `id` of the
+ * block to point at — a stable string the render tags onto that block with
+ * `data-next-action` — or `null` when nothing is pending. Pure and
+ * dependency-free so it can be unit tested without a DOM: the renderer imports
+ * it, `node --test` requires it directly, exactly like `setup-steps.cjs`.
+ *
+ * The order below is a priority ladder, most urgent first. It is deliberate,
+ * not incidental: an incomplete update (the code moved but the built assets did
+ * not, so the site may not run) outranks everything, because ignoring it wastes
+ * the rest of the session. A stale tree outranks routine work because a patch
+ * made against old code may not apply on Trac. Only then do the routine steps
+ * come — get the server up, review pending changes, link a ticket — and a site
+ * that is running, clean and linked has no next action at all.
+ *
+ * @param {Object}  state
+ * @param {boolean} state.skipInit         Init wizard skipped; post-init view shown.
+ * @param {?string} state.currentSetupStep The checklist's current step key, or null.
+ * @param {boolean} state.updateIncomplete Code updated but built assets are stale.
+ * @param {boolean} state.isUpdating       A trunk update is running now.
+ * @param {boolean} state.stale            The trunk snapshot is old (#94).
+ * @param {boolean} state.running          The dev server is up.
+ * @param {boolean} state.hasChanges       The working tree has uncommitted edits.
+ * @param {boolean} state.ticketLinked     A Trac ticket is linked.
+ * @return {?{id: string, reason: string}} The block to point at, or null.
+ */
+function deriveNextAction(state = {}) {
+	const skipInit = Boolean(state.skipInit);
+
+	// Before the wizard is skipped the checklist is the whole story, and it has
+	// already worked out its own next step (exactly one row is `current`). Reuse
+	// that rather than re-deriving it from the raw flags — there is one source of
+	// truth for the checklist, and it is the checklist.
+	if (!skipInit) {
+		if (typeof state.currentSetupStep === 'string' && state.currentSetupStep) {
+			return {
+				id: `setup-${state.currentSetupStep}`,
+				reason: 'The next step in the setup checklist.'
+			};
+		}
+		return null;
+	}
+
+	if (Boolean(state.updateIncomplete) && !Boolean(state.isUpdating)) {
+		return {
+			id: 'retry-install-build',
+			reason: 'The update left the build stale; install and build to recover.'
+		};
+	}
+
+	// An update in flight is not an action, but it is the thing happening — point
+	// at its tracker so a contributor who looked away can find where the work is.
+	if (Boolean(state.isUpdating)) {
+		return { id: 'updating', reason: 'The trunk update in progress.' };
+	}
+
+	if (Boolean(state.stale)) {
+		return {
+			id: 'update-trunk',
+			reason: 'The trunk snapshot is old; update before making a patch.'
+		};
+	}
+
+	if (!Boolean(state.running)) {
+		return { id: 'start-dev', reason: 'Start the dev server to work on the site.' };
+	}
+
+	if (Boolean(state.hasChanges)) {
+		return {
+			id: 'review-changes',
+			reason: 'You have uncommitted changes ready to review and submit.'
+		};
+	}
+
+	if (!Boolean(state.ticketLinked)) {
+		return { id: 'link-ticket', reason: 'Link a Trac ticket to give your work a home.' };
+	}
+
+	return null;
+}
+
+module.exports = { deriveNextAction };
@@ -0,0 +1,118 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const { deriveNextAction } = require('../src/renderer/next-action.cjs');
+
+test('during setup, the next action is the checklist\'s current step', () => {
+	const next = deriveNextAction({ skipInit: false, currentSetupStep: 'install' });
+
+	assert.deepStrictEqual(next && next.id, 'setup-install');
+});
+
+test('setup defers entirely to the checklist, ignoring post-init flags', () => {
+	// The post-init flags below would each point somewhere if the wizard were
+	// skipped; while the checklist shows, none of them may override it.
+	const next = deriveNextAction({
+		skipInit: false,
+		currentSetupStep: 'build',
+		updateIncomplete: true,
+		stale: true,
+		running: false
+	});
+
+	assert.strictEqual(next.id, 'setup-build');
+});
+
+test('during setup with no current step, nothing is pointed at', () => {
+	const next = deriveNextAction({ skipInit: false, currentSetupStep: null });
+
+	assert.strictEqual(next, null);
+});
+
+test('an incomplete update outranks everything post-init', () => {
+	const next = deriveNextAction({
+		skipInit: true,
+		updateIncomplete: true,
+		stale: true,
+		running: false,
+		hasChanges: true,
+		ticketLinked: false
+	});
+
+	assert.strictEqual(next.id, 'retry-install-build');
+});
+
+test('an update in flight suppresses the retry banner and points at its tracker', () => {
+	// updateIncomplete is set during the window an update owns the tree; while the
+	// update is actually running there is nothing to retry, only progress to find.
+	const next = deriveNextAction({
+		skipInit: true,
+		updateIncomplete: true,
+		isUpdating: true
+	});
+
+	assert.strictEqual(next.id, 'updating');
+});
+
+test('a stale tree outranks the routine steps', () => {
+	const next = deriveNextAction({
+		skipInit: true,
+		stale: true,
+		running: false,
+		hasChanges: true,
+		ticketLinked: false
+	});
+
+	assert.strictEqual(next.id, 'update-trunk');
+});
+
+test('with nothing urgent, the first routine step is starting the dev server', () => {
+	const next = deriveNextAction({
+		skipInit: true,
+		running: false,
+		hasChanges: true,
+		ticketLinked: false
+	});
+
+	assert.strictEqual(next.id, 'start-dev');
+});
+
+test('a running server with pending changes points at reviewing them', () => {
+	const next = deriveNextAction({
+		skipInit: true,
+		running: true,
+		hasChanges: true,
+		ticketLinked: false
+	});
+
+	assert.strictEqual(next.id, 'review-changes');
+});
+
+test('a running, clean site with no ticket points at linking one', () => {
+	const next = deriveNextAction({
+		skipInit: true,
+		running: true,
+		hasChanges: false,
+		ticketLinked: false
+	});
+
+	assert.strictEqual(next.id, 'link-ticket');
+});
+
+test('a running, clean, linked site has no next action', () => {
+	const next = deriveNextAction({
+		skipInit: true,
+		running: true,
+		hasChanges: false,
+		ticketLinked: true
+	});
+
+	assert.strictEqual(next, null);
+});
+
+test('missing state is treated as nothing pending, not a crash', () => {
+	assert.strictEqual(deriveNextAction(), null);
+	assert.strictEqual(deriveNextAction({}), null);
+});