docs: README quick-start for fresh pulls (bootstrap, rebuild, serve-lan)

Top section now leads with the rebuild-after-pull workflow (public/ is never
in git) including make bootstrap/tool-versions and the error-127 hint; §2
recommends bootstrap over manual installs; §4 documents the new targets; §7
gains the pagefind/livereload-404 and command-not-found bullets; §8 lists
.tools/.

README.md

@@ -11,8 +11,35 @@ previewing, searching, and maintaining the site.
 
 ---
 
+## Fresh git pull? Rebuild before serving
+
+`public/` (the built site) is **never in git** — it's regenerated locally and
+gitignored (§8). A `git pull` brings you source only: content, theme, Makefile,
+scripts. Until you rebuild, there is nothing to serve — and a stale `public/`
+left over from an older workflow (e.g. `hugo server`) will render pages with a
+broken search box and spurious `pagefind/*` / `livereload.js` 404s in the server
+log.
+
+From the project root:
+
+```
+make bootstrap            # ONCE per machine: pinned Hugo/Node/lychee into .tools/ (no system changes)
+make tool-versions        # diagnostic: pinned vs system tool versions
+make clean && make all    # wipe stale output, then hugo --gc + pagefind index
+make serve-lan            # serve on http://<LAN-IP>:8090/   (or: make serve, local :1414)
+```
+
+Success check: the `make all` log prints `Indexed N pages` (N > 0) and
+`public/pagefind/pagefind-ui.js` exists. `error 127` / "command not found"
+means a tool is missing: `make tool-versions` shows which, `make bootstrap`
+fixes it. Full details: [Prerequisites (§2)](#2-prerequisites-install-once),
+[Build & preview (§4)](#4-build--preview-make-commands).
+
+---
+
 ## Table of contents
 
+- [Fresh git pull? Rebuild before serving](#fresh-git-pull-rebuild-before-serving)
 - [Architecture](#architecture)
 - [1. Clone](#1-clone)
 - [2. Prerequisites (install once)](#2-prerequisites-install-once)
@@ -196,6 +223,13 @@ cd libertytoolsio
 
 ## 2. Prerequisites (install once)
 
+**Recommended: `make bootstrap`.** It installs pinned versions of Hugo extended
+(0.167.0), Node (22.11.0 — provides `npx` for Pagefind), and lychee (0.24.2)
+into the repo-local `.tools/bin` (gitignored). Make targets always use these
+pinned tools via a recipe-scoped PATH; your system PATH and any system-installed
+tools (e.g. an older Hugo) are never touched. Run `make tool-versions` to see
+pinned vs system versions side by side. The manual per-tool installs below are
+the fallback (they install into `~/.local/bin`).
 All tools install into `~/.local/bin` (no sudo). Make sure `~/.local/bin` is on your
 `PATH` (it usually is; if not: `export PATH="$HOME/.local/bin:$PATH"`).
 
@@ -235,11 +269,14 @@ All tools install into `~/.local/bin` (no sudo). Make sure `~/.local/bin` is on
 
 ## 4. Build & preview (make commands)
 
-Run from the project root. `public/`, `linkcheck/`, and `resources/_gen/` are
+Run from the project root. `public/`, `linkcheck/`, `resources/_gen/`, and
-generated and gitignored.
+`.tools/` are generated and gitignored.
 
 | Target                | What it does |
 |-----------------------|--------------|
+| `make bootstrap`      | **Once per machine.** Install the pinned toolchain (Hugo 0.167.0 extended, Node 22.11.0, lychee 0.24.2) into repo-local `.tools/bin`. Idempotent; never touches your system. |
+| `make tool-versions`  | Diagnostic table: pinned (`.tools/bin`) vs PATH-first (system) tool versions. |
+| `make preflight`      | Strict tool check (runs automatically before `all`/`serve`/`serve-lan`); on failure it says `make bootstrap` instead of a bare `error 127`. |
 | `make build`          | Build Hugo content into `public/` (`hugo --gc`). |
 | `make index`          | `build` + build the Pagefind search index into `public/pagefind/`. **This is the normal "I edited content, re-make it" command.** |
 | `make serve` / `make run` | `index` + serve the built site **with search** at `http://localhost:1414/` (local only). Uses Pagefind's own server, which binds 127.0.0.1. |
@@ -377,6 +414,12 @@ hermes cronjob list            # confirm it exists and is enabled
 
 ## 7. Troubleshooting
 
+- **Server log shows 404s for `/pagefind/*` or `/livereload.js`** → stale or
+  unindexed `public/`: run `make clean && make all` and restart the server (see
+  [Fresh git pull? Rebuild before serving](#fresh-git-pull-rebuild-before-serving)).
+- **`error 127` / "command not found"** → a build tool is missing. Run
+  `make tool-versions` to see which, then `make bootstrap` to install the
+  pinned toolchain into `.tools/`.
 - **`hugo: command not found`** → you're using the non-extended build or it isn't on
   PATH. Re-run the Hugo install above and confirm `hugo version` says `+extended`.
 - **Search shows no results** → the index wasn't built. Run `make index`, confirm the
@@ -404,9 +447,11 @@ All changes from a maintenance pass are left in the working tree for review. Com
 **only after you have validated the result** (`make build` exits 0 and you've checked
 the rendered output). The following are generated and gitignored — never commit them:
 
-- `public/` — built site output
+- `public/` — built site output; a fresh clone/pull contains none of it (rebuild
+  per [Fresh git pull? Rebuild before serving](#fresh-git-pull-rebuild-before-serving))
 - `linkcheck/` — link-check reports
 - `resources/_gen/` — Hugo asset-generation cache
+- `.tools/` — pinned local toolchain installed by `make bootstrap`
 - `.hermes/` — agent working files
 
 ## Repository layout