Describe what the toolkit does at 1.0 in the README

[juanmaguitar]

Why

v1.0.0 is published, but the repository's front page still describes the app as it was at
v0.1.x: a thing that sets up a development environment with no prerequisites, full stop. Nothing
that 1.0 is actually about appears on it — linking a Trac ticket, reading its facts, applying the
pull requests and patches already on it, holding work for several tickets in one site, debugging,
or sending a change back as a pull request, a Trac attachment or a mentor handoff.

### Why had the same problem in argument form: it makes the case against setup friction, which is
the wall v0.1.x removed, and stops there.

Someone arriving from the Make announcement or from the release page reads this file first. It was
underselling the release they had just heard about.

What changes

README.md. The top of the file only; every section about contributing to this repository —
Build from source, App icon, Why Electron?, Ideas and future work, Download stats,
Contributing, License — is current and untouched.

• The description paragraph now covers the whole loop rather than only setup, including the two
  guarantees that are easy to miss and hard to re-derive: nothing installed on the host, and no push
  credential written to disk.
• ### Why keeps the Contributor-Day setup argument as it was and adds the second wall: a newcomer
  with a running environment still has to find the existing patch, get it into the checkout,
  understand a failed apply, and work out that WordPress reviews on Trac but takes pull requests on
  GitHub.
• A new What you can do with it section: seven capabilities, each linking the guide page that
  already documents it, so the README stays a map and the guide stays the manual.
• Both YouTube blocks are removed. They show the pre-1.0 interface, and the second one demonstrates
  the patch screen that 1.0 reworked. Their thumbnails, docs/setup-start.png and
  docs/create-patch.png, are deleted with them — the README was their only reference.
• One current screenshot near the top, site-view.png, served from the docs site. This was not
  asked for: removing two images and adding none leaves the page worse, and this is the image the
  release notes and the announcement both open with. Say so if you would rather the README carried
  no image.

package.json. description was Electron app to setup WordPress develop structure and run npm install. electron-builder carries this into the packaged application's metadata, so it is
user-visible, and it described a subset of v0.1.x. It now describes the app. No other field
changes.

Not in this PR, for JuanMa to apply in Settings: the GitHub repository description is still
"An experiment to explore an easy to install core WordPress development environment app". Proposed
replacement, same sentence as the new package.json description:

Desktop app that sets up a WordPress core development environment with no prerequisites, applies
the work already on a Trac ticket, and submits a contribution back.

How to test this

Platforms: any; this is documentation and package metadata.

1. Run npm run lint and npm test.

   • Expected: lint succeeds and all 1,027 tests pass.

2. Run npm run docs:build.

   • Expected: the VitePress build completes, confirming nothing under docs/ referenced the two
     deleted images. It does not validate the README's links: README.md is not part of the
     docs source tree, and the links are absolute external URLs, which ignoreDeadLinks does not
     reach. Step 3 is what checks those.

3. From the repository root, confirm every guide page the README links actually exists:

   for p in $(grep -o 'contributor-toolkit/guide/[a-z-]*' README.md | sed 's|.*/guide/||' | sort -u); do
     test -f "docs/guide/$p.md" && echo "ok    $p" || echo "MISSING $p"
   done

   • Expected: 16 lines, all ok.

4. View README.md rendered on this branch on GitHub.

   • Expected: the three badges load, the screenshot loads, and every link in What you can do with
     it opens a real guide page rather than a 404.

5. Run node -p "require('./package.json').description".

   • Expected: the new sentence.

What must not have happened: no source file, workflow or build configuration in the diff; the
version and every dependency unchanged.

Risks and limitations

The main risk in a change like this is a claim that reads well and is not true. Every capability
listed was checked against the guide page it links and against the shipped behaviour rather than
against memory; the review below covers that specifically.

The screenshot is hotlinked from the docs site rather than committed, so it tracks whatever the
shots harness last published. That keeps it from going stale silently, at the cost of depending on
Pages being up — the same trade the release notes make.

The new description is 163 characters. It reaches the AppImage and deb .desktop Comment, the
deb control Description and the snap description; no length ceiling is hit and no build breaks.
Snap's 78-character limit applies to summary, which electron-builder fills from productName.
One cosmetic consequence: Debian's lintian warns description-too-long on a synopsis over 80
characters, so the .deb picks up a warning it did not have before. Not a build failure, not
user-visible.

Related

Follows v1.0.0 (#343, #344).

---

Review outcome (required — see AGENTS.md)

0 [fix here] · 0 [follow-up]. No findings across architecture, security, performance,
cross-platform or tests. npm run lint, npm test (1,027/1,027) and npm run docs:build pass.

Because the risk in this change is a claim that reads well and is false, the review was pointed at
the claims themselves. Each was traced to code, not to memory:

• no push credential written to disk — the token exists only as githubToken in src/main.js:775,
  cleared at :783, passed by value into src/github-pr.cjs. No store.set, no keychain, no file
  write.
• says which regions failed and why, and leaves the checkout untouched — src/patch-apply.js
  validates before writing. The one path that does write is a rollback after a disk error mid-write
  (src/patch-apply.js:526-530), which is a write failure rather than a patch that will not apply;
  the guide draws the line in the same place.
• each ticket gets its own branch inside the site — src/ticket-branches.js:4-23.
• fatals surfaced instead of hidden behind the recovery screen — src/wp-debug-constants.js:47
  sets WP_DISABLE_FATAL_ERROR_HANDLER: true.
• a terminal using the Node.js runtime the app bundles — src/script-runner.js:26,36 spawn
  process.execPath; src/npm-runner.js:88 sets ELECTRON_RUN_AS_NODE=1.
• keeps your name on the work — src/patch-provenance.cjs.
• fetching only what changed — src/trunk-update.js:269-273, depth: 1.
• with a rebuild when one is needed — conditional rather than decorative:
  src/renderer/update-plan.cjs:144 skips the build when the watcher is live.
• The Trac field list maps 1:1 onto src/trac-ticket-info.cjs:133-142.

Also verified: no doc page, workflow, issue template or scripts/screenshots/ entry referenced
either deleted PNG or either YouTube URL; every guide target exists; and the extensionless link form
is what the file already used on trunk and what Pages resolves through its .html fallback.

The review corrected one claim in this PR's own test plan: npm run docs:build does not validate
the README's links, because README.md is not in the docs source tree and the links are absolute
external URLs. Step 2 above has been rewritten to say so, and step 3 is what actually checks them.