fix: apply fresh-start review findings

Independent review (second attempt) passed all 7 verification steps at
19f6007, including the fresh-clone embed check, full build from clean
state (9.7s), server curl matrix (public 200, protected + all theme
sidecars 503, searchindex 404, no content in 503 bodies), and just check.

Findings applied:
- README: prerequisite Go version corrected to 1.27.1+ to match go.mod
  (a Go 1.22-1.27 user got a hard 'requires go >= 1.27.1' failure).
- CI: upload-artifact v3 -> v4 with a fallback note for older runners;
  CI now also runs the gofmt guard like 'just check'.
- Justfile: curl -fsSL so a bad download fails at curl instead of tar;
  comment clarifying that --dest-dir is resolved relative to docs/.
- AGENT.md: version-pairing trap now covers both pin locations
  (Justfile and .gitea/workflows/build.yml).

.gitea/workflows/build.yml

@@ -36,10 +36,13 @@ jobs:
         run: |
           go vet ./...
           go test ./...
+          test -z "$(gofmt -l cmd internal embed.go)" || { echo 'gofmt needed:'; gofmt -l cmd internal embed.go; exit 1; }
           CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o yggdrasil-server ./cmd/server
 
+      # upload-artifact v4 needs a reasonably current Gitea/act_runner;
+      # fall back to v3 if your runner is too old to serve v4 artifacts.
       - name: Upload server artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: yggdrasil-server-linux-amd64
           path: yggdrasil-server

AGENT.md

@@ -53,7 +53,9 @@ the user wins.
 
 - Shiroa version pairing: the CLI and the `@preview/shiroa:*` typst package
   must match (CLI v0.4.0-rc2 pairs with package 0.4.0; the v0.3.0 release
-  CLI rejects 0.4.0 books). Bump both together and rebuild.
+  CLI rejects 0.4.0 books). The pin lives in two places: the Justfile
+  `shiroa-version` and `.gitea/workflows/build.yml`. Bump all of them
+  together with the package import and rebuild.
 - Typst call syntax: no space between `)` and the trailing content block —
   `#chapter("x.typ")[Title]`, not `#chapter("x.typ") [Title]`.
 - `dist/` and `acl.json` are embedded at Go build time; there is no runtime

Justfile

@@ -22,9 +22,10 @@ parse:
 # Download the pinned shiroa into tools/ if missing.
 tools:
 	@mkdir -p {{shiroa-dir}}
-	@test -x {{shiroa-bin}} || { echo "Downloading shiroa {{shiroa-version}} ({{shiroa-target}})..."; curl -sSL -o {{shiroa-dir}}/shiroa.tar.gz {{shiroa-url}}; tar -xzf {{shiroa-dir}}/shiroa.tar.gz -C {{shiroa-dir}}; rm {{shiroa-dir}}/shiroa.tar.gz; {{shiroa-bin}} --version; }
+	@test -x {{shiroa-bin}} || { echo "Downloading shiroa {{shiroa-version}} ({{shiroa-target}})..."; curl -fsSL -o {{shiroa-dir}}/shiroa.tar.gz {{shiroa-url}}; tar -xzf {{shiroa-dir}}/shiroa.tar.gz -C {{shiroa-dir}}; rm {{shiroa-dir}}/shiroa.tar.gz; {{shiroa-bin}} --version; }
 
 # Compile the Typst book into dist/.
+# (--dest-dir is resolved relative to the book directory, docs/, hence ../dist)
 build-docs: tools
 	{{shiroa-bin}} build docs --dest-dir ../dist
 

README.md

@@ -57,7 +57,8 @@ legacy_docs/             the old documentation base (kept for manual migration)
 
 ## Quick start
 
-Prerequisites: Go 1.22+ and [just](https://github.com/casey/just). The
+Prerequisites: Go 1.27.1+ (the version required by `go.mod`) and
+[just](https://github.com/casey/just). The
 pinned shiroa toolchain is downloaded automatically into `tools/` on the
 first build (needs `curl` + `tar` and network access); nothing is
 installed globally.