Format Markdown with prettier in make fmt and make fmt-check (closes #19)

script/fmt and script/fmt-check run prettier over every Markdown file
again, next to gofmt. prettier is pinned by hash through package.json
and yarn.lock, copied from the prompts repo with .prettierrc and
.prettierignore, and is never installed on a host: a new prettier stage
of the Dockerfile installs it into a digest-pinned node image, and both
scripts build that stage and run it with the repository mounted. CI
checks the Markdown in a markdown stage that the build stage waits on.
Because make fmt-check now runs docker, the Dockerfile runs gofmt
directly in its lint stage instead. All Markdown is reformatted.

Model: opus-5-5

Dockerfile

@@ -12,9 +12,9 @@ COPY . .
 # build would exit 0 having run nothing. script/cibuild and
 # script/docker pass a fresh CHECK_EPOCH on every invocation.
 #
-# Two properties this depends on. ARG is per-stage, so the build stage
-# below declares it again; one declaration here would leave that
-# stage's gate cacheable. And each gate RUN must reference the value,
+# Two properties this depends on. ARG is per-stage, so the markdown and
+# build stages below declare it again; one declaration here would leave
+# their gates cacheable. And each gate RUN must reference the value,
 # because BuildKit hashes the expanded command: a declared but
 # unreferenced ARG invalidates nothing.
 #
@@ -27,9 +27,16 @@ ARG CHECK_EPOCH
 # target now runs `docker build -f Dockerfile.lint`, and a docker build
 # cannot run a docker build: routing the gate through make would mean
 # nesting docker inside this image. Same reason `make check` is gone
-# from the build stage below. `make fmt-check` stays as it is — it is a
-# gate, not the aggregate, and it shells out to nothing.
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
+# from the build stage below, and `make fmt-check` from both stages: it
+# runs prettier through docker too. Its gofmt half is the step below,
+# its Markdown half the markdown stage further down. gofmt's output is
+# assigned to a variable first so that its own exit status, as when it
+# cannot parse a file, still fails the step.
+RUN echo "gate gofmt, epoch ${CHECK_EPOCH}" && \
+    files="$(gofmt -s -l .)" && \
+    if [ -n "$files" ]; then \
+        echo "gofmt: files not formatted:" >&2; echo "$files" >&2; exit 1; \
+    fi
 
 # The FROM above and the one in Dockerfile.lint pin the same linter
 # twice, and nothing else keeps them in sync; this fails the build when
@@ -46,6 +53,30 @@ RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
 RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
     golangci-lint run --config .golangci.yml ./...
 
+# Prettier stage: the prettier that formats this repository's Markdown,
+# never installed on a host. script/fmt and script/fmt-check build this
+# stage alone and run it with the repository mounted on /src. prettier
+# is installed in /tools so that the repository, mounted or copied onto
+# /src, cannot hide it.
+# node:22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS prettier
+WORKDIR /tools
+# yarn.lock pins prettier by hash, and --frozen-lockfile fails rather
+# than install anything yarn.lock does not name.
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+ENV PATH=/tools/node_modules/.bin:$PATH
+WORKDIR /src
+
+# Markdown stage: the Markdown half of `make fmt-check`, as a gate.
+FROM prettier AS markdown
+COPY . .
+# Second per-stage declaration of the gate cache-buster; see the lint
+# stage above.
+ARG CHECK_EPOCH
+RUN echo "gate prettier, epoch ${CHECK_EPOCH}" && \
+    prettier --check '**/*.md' --tab-width 4 --prose-wrap always
+
 # Build stage
 # golang:1.25-alpine, 2026-07-23
 FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
@@ -70,15 +101,17 @@ ENV GOCACHE=/home/builder/.cache/go-build
 
 WORKDIR /src
 
-# No-op file copy whose only purpose is the build-graph edge: it is what
-# makes this stage depend on the lint stage, and so what forces BuildKit
-# to finish fmt-check, the pin guard and lint before compilation and
-# tests start. Remove it and the fail-fast design dies silently — the
-# build stops gating on lint and still exits 0. It replaces a copy of
-# the linter binary itself, which is no longer wanted here: nothing in
-# this stage runs the linter, because `make lint` is now a docker build
-# and a docker build cannot run inside one.
+# No-op file copies whose only purpose is the build-graph edge: they are
+# what make this stage depend on the lint and markdown stages, and so
+# what forces BuildKit to finish gofmt, the pin guard, lint and prettier
+# before compilation and tests start. Remove one and the fail-fast
+# design dies silently — the build stops gating on that stage and still
+# exits 0. The first replaces a copy of the linter binary itself, which
+# is no longer wanted here: nothing in this stage runs the linter,
+# because `make lint` is now a docker build and a docker build cannot
+# run inside one.
 COPY --from=lint /src/go.sum /dev/null
+COPY --from=markdown /src/go.sum /dev/null
 
 # Install development prerequisites the same way a developer does,
 # rather than duplicating the installs inline. Only script/ and the
@@ -112,19 +145,19 @@ USER builder
 # permission-denied test paths are exercised legitimately (root would
 # bypass the chmod(0) the tests rely on).
 #
-# The gates are the individual targets, not `make check`: that aggregate
-# runs `script/lint`, which is now a docker build, and nothing inside an
-# image build may shell out to docker. Lint is not skipped by this — it
-# ran in the lint stage above, which this stage's COPY --from makes a
-# prerequisite. `make`, not the scripts directly, because the Makefile's
+# The gate is `make test`, not `make check`: that aggregate runs
+# `script/lint` and `script/fmt-check`, which both run docker, and
+# nothing inside an image build may shell out to docker. Lint and the
+# format checks are not skipped by this — they ran in the lint and
+# markdown stages above, which this stage's COPY --from lines make
+# prerequisites. `make`, not the script directly, because the Makefile's
 # `export CGO_ENABLED = 0` applies only to what it invokes.
 #
-# Second per-stage declaration of the gate cache-buster; see the lint
+# Third per-stage declaration of the gate cache-buster; see the lint
 # stage above for why one is not enough. It is placed after USER so the
 # drop to the unprivileged user still happens before the checks run.
 ARG CHECK_EPOCH
 RUN echo "gate test, epoch ${CHECK_EPOCH}" && make test
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
 
 # The version stamped into the binary: the VERSION build argument when
 # one is given, otherwise `git describe --tags --always` of the .git in