Add the VitePress documentation site and its Pages deploy workflow

[juanmaguitar]

Why

The app's user documentation is the README, and it has outgrown it: install steps, a ten-step
walkthrough and the trunk-update rules all compete for the same page, and there is nowhere to put
a screenshot. This PR gives the guide a home and a deploy pipeline. It carries no guide content
beyond the landing page — that arrives in #232, and the harness that photographs the app in #231.

What changes

• docs/ becomes a VitePress site with its own npm package, so a docs-only CI job never runs
  the root postinstall (electron-builder + esbuild) and the app's dependency tree stays free of
  a static-site generator.
• .github/workflows/docs.yml builds and deploys to GitHub Pages on pushes to trunk that touch
  docs/. Pull requests get a build-only job: a dead link fails before merge, and the job
  holding the OIDC token never runs on PR code.
• The site's base is derived from the repository name at run time. A project Pages site is served
  under /<repo-name>/, and this repo has already been renamed once — deriving it means another
  rename cannot break every asset URL.
• srcExclude keeps docs/testing.md (from e2e: packaged-app smoke test on macOS and Windows #70) out of the published site: it documents how to
  run the suites, which is contributor material, and this site is for users of the app.

How to test this

Starting state: this branch checked out, npm ci done.

1. npm run docs:build — expect build complete. Now add a link to a page that does not exist in
   docs/index.md and run it again: it must fail with dead link(s) found. Undo.
2. npm run docs:preview, open the printed URL — the home page renders with the WordPress
   Contributor Toolkit hero and the sidebar. Clean URLs work; this is exactly what Pages serves.
3. npm run docs:dev — pages are served at their .html paths in dev (/index.html). With the
   dev server open, run npm run docs:build in another terminal: the dev server must not spew
   reload lines (it ignores its own output directory).
4. npm run lint and npm test — both green, unchanged from trunk.

Must not have happened: no deploy job may run on this pull request — check the Actions tab
and confirm only build site ran.

Not testable by hand here: the deploy itself. It needs the workflow on trunk, and Pages is
already set to "GitHub Actions" as its source.

Risks

Merging this alone deploys a site whose sidebar names the full guide, so those links 404 until
the content PR lands. Merge the stack in order rather than leaving this on trunk by itself.

The deploy job holds pages: write and id-token: write. Its actions are pinned to commit SHAs
rather than tags, following the reasoning already written down in download-stats.yml.

Related

Stack: this → #231 (screenshot harness) → #232 (guide content).
Touches #70 only through srcExclude; that PR needs no change.

---

Self-review — 5 findings, all fixed

Ran .github/instructions/code-review.instructions.md with the judgement pass in a fresh context.
Deterministic layer was clean (ESLint and the unit suite on macOS and Windows).

5 [fix here] · 1 [follow-up]. All five fixed in this branch:

Dimension	Was	Now
security 🟡	checkout kept the job's GITHUB_TOKEN in .git/config while the job runs PR-authored code (npm ci with lifecycle scripts, and a VitePress build that evaluates config.mjs)	persist-credentials: false, matching lint.yml
security 🔵	if: github.event_name != 'pull_request' let a workflow_dispatch on any ref publish to the live site, which is not what the comment claimed	if: github.ref == 'refs/heads/trunk'
cross-platform 🔵	node-version: 22 hardcoded while .nvmrc says 24.18.0 — reintroducing the Node drift of #37/#46 for the one command CONTRIBUTING calls "what CI runs"	node-version-file: .nvmrc
architecture 🔵	one concurrency group spanning build and deploy, with cancel-in-progress: true, so a second push could cancel an in-flight deploy-pages	split: builds cancel, deploys do not
architecture 🔵	CONTRIBUTING documented docs:* without saying the nested package needs its own install, so the commands fail on a clean clone	npm ci --prefix docs documented

Deferred [follow-up]: electron-builder has no files filter, so tracked docs/ sources ship
inside app.asar — and #232 adds screenshots on top. Real, pre-existing, and overlaps #23; an
!docs{,/**/*} entry closes it. Not done here because it changes what every release artifact
contains, which deserves its own PR and its own testing.

Checked and clean: all four action pins resolve to the tags their comments claim (verified
against the GitHub API); pull_request_target is correctly not used and no fork PR can reach
pages: write / id-token: write; the lockfile is 175 packages, all from registry.npmjs.org, with
install scripts only on esbuild and fsevents; the import/no-unresolved exemption is a genuine
false positive and hides nothing; no src/ code, IPC surface or spawn path is touched.