From 9ffc6a14d2a150ef9c8f429478bf769aedd6c579 Mon Sep 17 00:00:00 2001
From: Klagarge <remi@heredero.ch>
Date: Sat, 10 Oct 2026 19:05:34 +0200
Subject: [PATCH] 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 | 5 ++++-
 AGENT.md                   | 4 +++-
 Justfile                   | 3 ++-
 README.md                  | 3 ++-
 4 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/.gitea/workflows/build.yml b/.gitea/workflows/build.yml
index cd92699..3cb2105 100644
--- a/.gitea/workflows/build.yml
+++ b/.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
diff --git a/AGENT.md b/AGENT.md
index a16c346..02dc525 100644
--- a/AGENT.md
+++ b/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
diff --git a/Justfile b/Justfile
index d1cc004..42290dc 100644
--- a/Justfile
+++ b/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
 
diff --git a/README.md b/README.md
index 14bf598..0348d94 100644
--- a/README.md
+++ b/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.