Repository navigation
Bring the guide back in line with the app before 1.0 - #297
Merged
Merged
Conversation
Six changes since v1.0.0-beta.1 moved behaviour the guide describes, and four of those descriptions are now simply false: the build watcher is no longer tied to the dev server's lifecycle (#247), a trunk update no longer needs the server stopped (#262), the setup checklist is no longer four clicks (#246), and the site URL now carries a wp-admin link the guide tells you to type by hand (#248). Corrected, and documented alongside them: the build watch's own control, dot and log tab; what a failed apply now says and why the answer differs for a pull request (#282); the ticket's own facts and the Latest pill's real ranking (#292, #281); Discard all changes rewinding to the ticket's base (#270); severity colour in the log panes (#280); and one passage on the "Start here" cue and the completion toasts (#252, #253), which are cross-cutting enough that repeating them per page would be worse. Screenshots are not retaken here — see the follow-up issue. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The self-review pass (per .github/instructions/code-review.instructions.md, dispatched to a fresh Explore subagent so the session that wrote the docs was not the one grading them) verified every behavioural claim against the actual source and found ten problems, five real enough to fix here: - The ☰ menu's "Update to latest trunk" entry is not disabled during an install/build — it silently no-ops. The rewritten trunk-updates.md had claimed both entry points were disabled; restored the correct behaviour. - The build watch stays green while it recompiles a save; amber only means the one-off pre-watch build or a pause for another action. Fixed the dot table. - planWatchImpact (update-plan.cjs) checks the lockfile only, not "src-only" — fixed the applying-patches.md and running-the-site.md claims accordingly. - "Read details from Trac" is a third action, not folded into "two"; it also disappears once details are loaded. - editors.md and creating-a-site.md, outside the original diff, still described the pre-#247/#246 world (watcher tied to the server; the wizard as steps you drive by hand) — now contradicted by running-the-site.md and setup-wizard.md. Brought both in line. Also softened three claims that were previously stated more strongly than the code supports: the watch tab title's "(stopped)" state (only shown for an unexpected exit, not a deliberate stop), "each region" showing add/remove lines (only the first few per file, per REGION_DETAIL_LIMIT), and the next-action cue as a labelled "Start here" pill (it is an unlabelled amber ring; the label was invented, not read off the code) plus its "always carries a next action" framing (deriveNextAction returns null on a clean, running, ticket-linked site). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
juanmaguitar
added a commit
that referenced
this pull request
Aug 12, 2026
Closes #298. ## Why #297 fixed the guide's text for everything that shipped since `v1.0.0-beta.1`, but three pictures still showed the pre-1.0 app: no build-watch button, the old four-click checklist, a Trac panel with no ticket facts. Retaking them turned out to be blocked on the harness, not on the camera. Each of these states is one no seeded site can reach: - the **wp-admin** link renders only while a dev server is serving, and fixture sites are empty directories; - the **self-setup chain** arms on the clone-finished edge, so a site that was already in the registry when the app started never runs it; - a **ticket's own facts** come from a live visit to its Trac page and are held in memory, never written to the site's metadata. ## What changes `shots.cjs` moves `setup-wizard`, `site-view` and `trac-ticket-panel` to the live tier, next to `dev-server-running`, ordered so one site walks all four in sequence. The header comment records why each cannot be a fixture, so the next person does not move them back. `capture.cjs` grows `--user-data=<dir>` for the live tier, so a capture session runs against a documentation profile instead of the maintainer's own registry. The existing guard stays — it exists so a stray *exported* `TOOLKIT_USER_DATA_DIR` cannot silently redirect a run, and a path typed on the command line is a decision, not a leftover. The flag is refused on the fixture tier, which builds its own throwaway profile. The four images come from one real site the app created at `/private/tmp/wpct-docs/my-first-patch` — a real clone, install, build, dev server and Trac read. No username in any pixel. `dev-server-running.png` is new, and answers the half of #298 a single picture could not: `site-view.png` stays in the stopped state, so the guide's "shows a **Start dev server** button" prose still matches, and the wp-admin link gets its own shot in *Running the site*. Re-running the fixture tier also refreshed `site-menu`, `stale-site-notice` and `debug-log`: same pre-1.0 button row, same fix. Alt text follows the new pictures in `getting-started.md`, `running-the-site.md`, `setup-wizard.md` and `trac-tickets.md`, and the `docs.yml` comment now says four shots need a maintainer. ## Review The ticket in the panel is [#65856](https://core.trac.wordpress.org/ticket/65856), which has no keywords set, so that row of the facts card is absent — the card renders what the ticket has. The images were driven programmatically rather than clicked by hand, using the same launch config the harness uses (1200×800, DPR 1) with the folder picker answered through `dialog.showOpenDialog`. The live tier itself is unchanged as the documented, maintainer-at-the-keyboard path. ## Testing - `npm run lint`, `npm test` (937 pass), `cd docs && npm run build` — green. - `npm run shots` (fixture tier) still captures its eight shots; `--only=site-view` on the fixture tier now fails loudly with the known-slug list, and `--user-data` on the fixture tier is refused. - Every image is 1200×800 at DPR 1, and no path in any picture contains a username. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Twenty PRs landed on
trunkbetweenv1.0.0-beta.1and this release candidate, and several moved behaviour the guide describes. Four of the guide's claims had gone from incomplete to simply false:running-the-site.mdsaid it ran "alongside the server… while the server is up"./wp-admin/onto the URL by hand.What changes
Correcting those four, and documenting what came with them: the build watch's own control, dot and log tab; what a failed apply says now and why the framing differs for a pull request versus a loose patch file (#282); the ticket's own facts and the "Latest" pill's real ranking (#292, #281); Discard all changes rewinding to the ticket's base (#270); severity colour in the log panes (#280); and one short passage on the "Start here" cue and the completion toasts (#252, #253) — cross-cutting enough that repeating them per page would read worse than naming them once.
Review
Ran
/self-reviewperAGENTS.md, dispatched to a freshExploresubagent so the session that wrote the docs was not the one grading them.npm run lint/npm testdon't apply — docs-only, no JS touched — so the review focused on the one dimension that does: every behavioural claim verified against the actual source, not assumed. It caught ten inaccuracies, five worth fixing here — including two pages I hadn't touched (editors.md,creating-a-site.md) that my changes torunning-the-site.md/setup-wizard.mdhad left contradicting. All five are fixed in the second commit; the other five were softened as follow-up-scale wording tightenings, folded into the same commit since they were one-line each.Not in this PR
Screenshots.
site-view.png,setup-wizard.pngandtrac-ticket-panel.pngnow show a UI that has moved on (Build watch button, wp-admin link, ticket-facts card). Retaking them needs the shots harness against a running app; filing a follow-up issue rather than blocking this PR on it.🤖 Generated with Claude Code