Skip to content

Bring the guide back in line with the app before 1.0 - #297

Merged
juanmaguitar merged 2 commits into
trunkfrom
juanmaguitar/docs-for-1.0.0-rc.1
Aug 12, 2026
Merged

juanmaguitar merged 2 commits into
trunkfrom
juanmaguitar/docs-for-1.0.0-rc.1

Conversation

@juanmaguitar

Copy link
Copy Markdown
Collaborator

Why

Twenty PRs landed on trunk between v1.0.0-beta.1 and this release candidate, and several moved behaviour the guide describes. Four of the guide's claims had gone from incomplete to simply false:

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-review per AGENTS.md, dispatched to a fresh Explore subagent so the session that wrote the docs was not the one grading them. npm run lint / npm test don'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 to running-the-site.md/setup-wizard.md had 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.png and trac-ticket-panel.png now 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

juanmaguitar and others added 2 commits August 12, 2026 10:08
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
juanmaguitar merged commit 5e04637 into trunk Aug 12, 2026
5 checks passed
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>
@juanmaguitar
juanmaguitar deleted the juanmaguitar/docs-for-1.0.0-rc.1 branch August 21, 2026 09:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant