[wayfinder] Agent-authored walkthrough — a pin set that tells the requester what to check on the dev server (map)

## Destination

When an implementation session ends, a webui-owned `walkthrough` skill mints a **Walkthrough** on the booted dev server — an ordered pin set whose stops say **what changed** and **what to check**, each carrying a GitHub "Files changed" line link — and hands its link to the requester in the final message and in one PR comment; the overlay walks the stops in a guided mode. The map is done when every decision the spec needs is made and written: an ADR (extending ADR 0002) and CONTEXT.md terms in `lablup/backend.ai-webui`, plus a Revision 4 section in `frontend-board/specs/pr-devserver-review.md`. Implementation follows as FRs under Epic FR-3313, outside this map.

## Notes

- **Plan, don't do.** Decision tickets only; prototypes are throwaway and linked from their ticket. Issues and comments in English. Resolve = resolution comment + Done + one line appended here.
- **Driver: Sujin Kim.** This effort revisits spec R3.1's "no `✅ What to check` comment" (driver decision by Jongeun Lee, 2026-09-01; FR-3814 Not Planned because its trigger was pinned to the shared `dw:impl` orchestrator). Spec R3.9 says a later wish is "a new ticket, not a revival" — this map is that new effort. The reversal is flagged to the previous driver through a task ticket, never silently.
- **Charting decisions (grilling, 2026-09-15):**
- Same Pin, same `#bai=v3` set grammar, same read side. New terms: **Mark** (the tinted changed element the docs preview draws instead of a pin glyph), **Navigator** (the bottom-right pill), **Walkthrough** (an ordered pin set the implementing agent leaves on the dev server, saying what changed and what to check) and **Stop** (one pin in it). Pin's CONTEXT.md definition widens from "one reviewer remark" to "one remark tied to one element", whoever authored it. Terms land in CONTEXT.md with the implementation.
- Authored automatically at the end of an implementation run by a **webui-owned skill** (`.claude/skills/walkthrough`, called by this repo's implementation workflow), not by dw/fw shared plugins.
- Anchors are minted **headless with Playwright** against the booted dev server, so every stop is verified to exist. No encoder CLI fallback.
- **Only on-screen changes become stops.** Hooks, tests, i18n, generated files stay in the PR description (no code-only stops).
- Code references are a **structured field** (`code: [{path, line}]`), rendered by the overlay as `pull/N/files#diff-R`; not markdown inside the note.
- The note splits into two capped fields, `changed` and `check` (~280 chars each), both riding in the anchor so the link alone is complete; `check` is phrased as an expected outcome; language = the requester's chat language.
- Each stop carries the **head SHA** it was made for; the overlay warns when the server serves a different commit. Line drift after rebase is accepted.
- Stops behind modals/tabs are allowed: the stop says how to get there, Playwright walks that path; unreachable stops are dropped and listed as "could not pin" in the PR comment.
- Reader UX is a **guided mode**: a walkthrough bar (N/M, prev/next across pages), `changed`/`check` and code links on the card, ✔ per stop in localStorage keyed by walkthrough, ✗ opens the existing compose pre-anchored to the stop (the reviewer-pin flow, no new channel).
- Delivery: the final chat message + **one PR comment** (idempotent marker, edited on re-run; block per stop in the existing block format + one code line, set link once, header "Walkthrough · N stops · ") — separate from the dev-server comment (FR-3784 role split). Teams: nothing.
- Stacks: one walkthrough **per layer**, each opened on the top server; code links use the layer's PR number.
- Order of stops = the requester's on-screen flow, not diff/execution order; `fw:pr-code-tour` is prior art only.
- Deliverable homes: overlay + skill + ADR + CONTEXT.md in webui; spec R4 in frontend-board; claude-mp untouched.
- `pr-ready-gate` does not re-mint: its Copilot-fix round is code-level, and UI-changing re-runs are covered by the implementing session's re-run rule (FR-3945); the gate never touches the walkthrough comment (driver decision, 2026-09-15).
- **Skills to consult:** `dev-server` (advertise.sh, boot record), `prototype`, `grilling`, `domain-modeling`, `adr-writing`. Prior art: ADR 0002, `react/vite-plugins/review-overlay/CONTEXT.md`, `e2e/review-overlay-deeplink.spec.ts` (in-page anchor minting), fw `pr-code-tour`, previous map FR-3782 / spec Revision 3.
- **Baseline facts (2026-09-15):** the overlay has ordering, note editing and a set dock but no external-link field, no code line reference (only the ⚛️ source location), no guided navigation. The note is capped inside the anchor (`NOTE_MAX`); a link costs ~300–500 chars per pin with a soft cap of 30. The CLI only parses. The nightly Amplify static build has no boot record (`pr=0`), so a code link cannot derive the PR number there — the payload must carry it or static builds are out.

## Decisions so far

- [Walkthrough payload — changed / check / code / sha fields in the v3 anchor and the link-length budget](https://lablup.atlassian.net/browse/FR-3942) — **v3 stays, additive**: a Stop adds optional `ch`/`ck` (≤280 each), `code[{path,line,to?}]`, `sha` (40-hex), `pr` (always, so static builds can link); today's codec already accepts it. Worst case 1.3K chars/stop, Korean ≈2× English; GitHub's 65,536-char comment binds before the URL, so **walkthroughs cap at 20 stops**; v4 envelope (3× smaller) stays deferred. Code link = `pull//files#diff-R[-R]`.
- [Minting anchors headless — Playwright on the booted dev server, including stops behind tabs and modals](https://lablup.atlassian.net/browse/FR-3943) — **works**: 4 stops (on load / modal / other page / launcher step) minted in 6–11 s each with the overlay's own in-page modules. Stop spec `{route, via[], find, ch, ck, code`}; `via` is replayed by the skill, rendered as a sentence by the overlay (never auto-clicked), and the overlay re-arms resolution on DOM mutation while a stop is current. Stops resolve **strictly** (landmark must match, `dlg: 1` in dialogs) after a measured false positive; volatile query params (`formValues`) get a codec-owned denylist; mint = box e2e admin + boot-record endpoint with an app-shell preflight; a verification pass drops failures into "could not pin".
- [Guided mode — walkthrough bar, cross-page prev/next, ✔ in localStorage, ✗ opens compose](https://lablup.atlassian.net/browse/FR-3944) — **the docs PR preview's grammar, ported as design**: tinted marks with the dashed orange outline plus an ordinal badge, the bottom-right navigator pill (`pages · changes │ i/N · viewed │ ✎ Copy N comments │ ‹ › ☰`), a popover with type chip, `old → new`, what to check, code links, Viewed and a comment box, `n/p/v/m/c` keys, a page banner that also carries the sha warning; state in localStorage per walkthrough; the walkthrough is a separate read-only set; cross-page `›` is an SPA push. Comments export as reviewer-pin blocks with `re: stop k`. Stops gain `type`, `kind`, `old`, `new`.
- [The walkthrough skill — choosing stops in user-flow order, writing changed / check, and where the impl workflow calls it](https://lablup.atlassian.net/browse/FR-3945) — webui-owned `.claude/skills/walkthrough/`, called by the implementing session as the last workflow step after `dev-server` advertises (dev-server untouched, also on demand); the session writes the stop manifest from the diff (one stop per on-screen-recognizable change, representative call site only, cap 20, ordered by the requester's flow, dialog stops after their opener), `scripts/mint.mjs` mints/verifies/reports; wording rules for `ch`/`ck`/`old`/`new`; preflight failure = one line, per-stop failure = a "could not pin" list with each `ck`; UI-changing re-runs re-mint and edit the comment in place; final message adds one `Walkthrough:` line.
- [The walkthrough PR comment — block per stop with a code line, header with sha, idempotent marker, one per stack layer](https://lablup.atlassian.net/browse/FR-3946) — one comment per PR under a single `` marker: header + **the set link once**, a numbered list (label, kind, `ch`, `old → new`, `check:`, `code:` file-line links), a "Could not pin" list; **no per-stop dev links** (~38K at 20 Korean stops vs 62K) and **no `bai-review` markers or `> 📍` blocks**, so the resolver never reads stops as findings (no claude-mp change); edited in place on re-mint; one per stack layer with a `Served by` line; the PR description gets a `## Walkthrough` section (comment URL + "Not shown" list).

## Not yet specified

- (none — **the map is complete.** Every decision the spec needs is in Decisions so far and the charting decisions in Notes; what remains is [Flag the reversal of spec R3.1's no-what-to-check decision to the previous driver](https://lablup.atlassian.net/browse/FR-3947), and then the hand-off: the ADR extending 0002, the CONTEXT.md terms, the Revision 4 section of `frontend-board/specs/pr-devserver-review.md`, and the implementation FRs under Epic FR-3313 — none of which is a ticket on this map.)

## Out of scope

- Notifying anyone that the run finished (R3.9 stays dropped) and any Teams write.
- Changes to the shared dw/fw plugins in claude-mp — the reason FR-3814 died.
- Code-only stops: changes without an on-screen element stay in the PR description (driver decision, Q7).
- Screenshots or before/after images in a stop (FR-3786 text-only v1 stands).
- Reuse for non-webui repositories.
- The nightly Amplify static build as a walkthrough surface — minting needs a dev server; reading is the same code and may work (no react-grab stack, no `Served by`/sha comparison without a boot record), but it is a side effect, not a target (driver decision, 2026-09-15).
- Screen-reader access of the marks and popover beyond the docs preview's `role=button` + aria-label — an implementation-time concern, as overlay verification was on the previous map.
- A walkthrough line on the My board card — `lablup/frontend-board`'s; an extension note in spec R4 only.
- Merging the docs PR preview overlay (`backend.ai-docs-toolkit` `pr-preview.js`) and the Web UI review overlay into one module — the guided mode ports the docs grammar as design only (FR-3944); a shared implementation is a later effort.

JIRA Issue: FR-3941

Start by reading ADR 0002, react/vite-plugins/review-overlay/CONTEXT.md, and frontend-board/specs/pr-devserver-review.md, then review the closed FR-3942 through FR-3946 decisions. The map is complete when the ADR extension, CONTEXT.md terms, Revision 4 section, and implementation hand-off under Epic FR-3313 are recorded; implementation itself is outside this issue.

Written by the indexing model from the issue text.