Install Dart Sass in CI

.claude/settings.json

@@ -11,9 +11,11 @@
       "Bash(git switch:*)",
       "Bash(git checkout:*)",
       "Bash(git add:*)",
+      "Bash(git commit:*)",
       "Bash(git restore:*)",
       "Bash(git stash:*)",
       "Bash(git fetch:*)",
+      "Bash(git push:*)",
       "Bash(git rev-parse:*)",
       "Bash(git ls-files:*)",
       "Bash(git mv:*)",
@@ -36,7 +38,6 @@
       "Skill(pre-pr:*)"
     ],
     "deny": [
-      "Bash(git push:*)",
       "Bash(git reset --hard:*)",
       "Bash(git clean -fdx:*)",
       "Bash(rm -rf /:*)",
@@ -45,7 +46,15 @@
       "Bash(gh release create:*)"
     ],
     "ask": [
-      "Bash(git commit:*)",
+      "Bash(git push --force*)",
+      "Bash(git push * --force*)",
+      "Bash(git push -f*)",
+      "Bash(git push * -f*)",
+      "Bash(git push -uf*)",
+      "Bash(git push * -uf*)",
+      "Bash(git push * +*)",
+      "Bash(git push --mirror*)",
+      "Bash(git push * --mirror*)",
       "Bash(git rebase:*)",
       "Bash(git merge:*)",
       "Bash(git cherry-pick:*)"

.github/workflows/check-links.yml

@@ -18,6 +18,12 @@ env:
   # SHA256 of the above tarball, pinned at download time. Update alongside
   # LYCHEE_VERSION_TAG whenever the binary is upgraded.
   LYCHEE_SHA256: "1f4e0ef7f6554a6ed33dd7ac144fb2e1bbed98598e7af973042fc5cd43951c9a"
+  # Pinned to the release the Spine sites were checked with. Newer releases
+  # add Sass deprecations, which nobody has checked against those sites yet.
+  DART_SASS_VERSION: 1.99.0
+  # SHA256 of `dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz`, from the GitHub release.
+  # Update alongside DART_SASS_VERSION.
+  DART_SASS_SHA256: "f0a32ab99bc0a1eb62ea7140a056a1bca82d534390b7c3dba4f2016eb0077753"
   # Force Hugo to write its module cache where the cache step actually
   # restores from. Hugo's default on Linux is `~/.cache/hugo_cache`
   # (or `$TMPDIR/hugo_cache_$USER`), neither of which matches the
@@ -79,6 +85,31 @@ jobs:
           hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
 
+      # The Spine Hugo theme compiles its SCSS with Dart Sass, because Hugo
+      # deprecated LibSass in v0.153.0 and will remove it. Hugo does not
+      # bundle Dart Sass: it runs the `sass` binary it finds on `PATH`, and
+      # a site on that theme fails to build without one. The release
+      # tarball is standalone, so no Node or Dart setup is needed. The
+      # checksum guards the download, as it does for Lychee below. Sites
+      # still on LibSass ignore the binary.
+      - name: Install Dart Sass
+        if: steps.docs.outputs.present == 'true'
+        run: |
+          archive="dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+          curl -fsSLO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/${archive}"
+          echo "${DART_SASS_SHA256}  ${archive}" | sha256sum --check --strict
+          tar -xzf "${archive}" -C "${RUNNER_TEMP}"
+          rm "${archive}"
+          echo "${RUNNER_TEMP}/dart-sass" >> "${GITHUB_PATH}"
+
+      # Hugo finds Dart Sass on `PATH`. `hugo env` lists it when it does.
+      # `GITHUB_PATH` only takes effect from the next step on, so this check
+      # cannot live in the install step above. It fails here, rather than
+      # mid-build, if the install did not put `sass` where Hugo looks.
+      - name: Check Dart Sass
+        if: steps.docs.outputs.present == 'true'
+        run: hugo env | grep 'github.com/sass/dart-sass'
+
       # `actions/setup-node@v4` ships with built-in npm caching that hashes
       # the lockfile and restores `~/.npm`. We use that instead of a
       # standalone `actions/cache@v4` block so there is only one source of

.github/workflows/gh-pages.yml

@@ -11,6 +11,12 @@ on:
 
 env:
   HUGO_VERSION: 0.169.0
+  # Pinned to the release the Spine sites were checked with. Newer releases
+  # add Sass deprecations, which nobody has checked against those sites yet.
+  DART_SASS_VERSION: 1.99.0
+  # SHA256 of `dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz`, from the GitHub release.
+  # Update alongside DART_SASS_VERSION.
+  DART_SASS_SHA256: "f0a32ab99bc0a1eb62ea7140a056a1bca82d534390b7c3dba4f2016eb0077753"
 
 jobs:
   deploy:
@@ -32,6 +38,29 @@ jobs:
           hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
 
+      # The Spine Hugo theme compiles its SCSS with Dart Sass, because Hugo
+      # deprecated LibSass in v0.153.0 and will remove it. Hugo does not
+      # bundle Dart Sass: it runs the `sass` binary it finds on `PATH`, and
+      # a site on that theme fails to build without one. The release
+      # tarball is standalone, so no Node or Dart setup is needed. The
+      # checksum guards the download. Sites still on LibSass ignore the
+      # binary.
+      - name: Install Dart Sass
+        run: |
+          archive="dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+          curl -fsSLO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/${archive}"
+          echo "${DART_SASS_SHA256}  ${archive}" | sha256sum --check --strict
+          tar -xzf "${archive}" -C "${RUNNER_TEMP}"
+          rm "${archive}"
+          echo "${RUNNER_TEMP}/dart-sass" >> "${GITHUB_PATH}"
+
+      # Hugo finds Dart Sass on `PATH`. `hugo env` lists it when it does.
+      # `GITHUB_PATH` only takes effect from the next step on, so this check
+      # cannot live in the install step above. It fails here, rather than
+      # mid-build, if the install did not put `sass` where Hugo looks.
+      - name: Check Dart Sass
+        run: hugo env | grep 'github.com/sass/dart-sass'
+
       - name: Setup Node
         uses: actions/setup-node@v3
         with:

.github/workflows/gradle-wrapper-validation.yml

@@ -1,19 +1,29 @@
 name: Gradle Wrapper validation
+
+# `migrate` distributes this workflow only to Hugo-only repositories that carry a
+# Gradle Wrapper. They keep the wrapper merely to run Hugo through Gradle tasks, and
+# none of their workflows sets Gradle up through `gradle/actions/setup-gradle`, so
+# nothing else checks that the wrapper JAR is genuine. A JVM repository does not
+# receive it: `setup-gradle`, used by every workflow that runs Gradle there,
+# validates the wrapper itself.
 on:
   push:
     branches:
-      - main
+      - master
   pull_request:
     branches:
       - '**'
 
+permissions:
+  contents: read
+
 jobs:
   validation:
     name: Validate Gradle Wrapper
     runs-on: ubuntu-latest
     steps:
       - name: Checkout latest code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Validate Gradle Wrapper
-        uses: gradle/actions/wrapper-validation@v4
+        uses: gradle/actions/wrapper-validation@v6

AGENTS.md

@@ -20,17 +20,29 @@ Shared skills, scripts, and guidelines come from the `.agents/shared` submodule
 (and some shallow clones / cloud checkouts) start with NO submodules checked out, so
 those symlinks dangle and no skills are found. Bootstrap such a tree with
 **`./init-submodules`** — a root script that materializes the missing
-*config-managed* submodules at their pinned commits: `config` itself, plus every
-submodule that declares a tracked `branch` in `.gitmodules` (`.agents/shared`, and
-any shared submodule added later) — the same rule `./config/pull` uses to decide
-what it floats. Submodules the consumer owns (a Hugo theme, a vendored library,
-doc-example submodules, …) declare no tracked branch and are left untouched, so the
-automatic `SessionStart` run never tries to clone — or fail on credentials for — a
-submodule this project does not manage. It depends on no pre-existing `config`
-submodule, so it works before `./config/pull` (which lives inside the `config`
-submodule) can. Claude Code runs it automatically via a `SessionStart` hook; other
-agents and humans run it by hand, then `./config/pull` to float the shared submodules
-to their branch tips.
+*config-managed* submodules at the tip of their branch (`master` for `config`, the
+tracked `branch` for the rest): `config` itself, plus every submodule that declares
+a tracked `branch` in `.gitmodules` (`.agents/shared`, and any shared submodule
+added later) — the same rule `./config/pull` uses to decide what it floats. It
+deliberately does not stop at the commit the superproject pins for such a
+submodule: nothing keeps that pin current — `ignore = all` hides the submodule from
+`git status`, and `./config/pull` floats the on-disk copy without committing the
+moved gitlink — so materializing the pin as-is means months-old hook scripts,
+skills, and guidelines. If the float fails — a branch the remote does not have,
+say — a warning is printed and the submodule is left wherever the steps that
+did succeed put it, at worst the pin, so a session still starts with a usable
+tree; it is not retried on a later run, which is why that warning points at
+`./config/pull`. With no network at all the clone itself fails and the
+submodule is left uninitialized, as it was before. Submodules the consumer owns
+(a Hugo theme, a vendored library, doc-example submodules, …) declare no tracked
+branch and are left untouched, so the automatic `SessionStart` run never tries
+to clone — or fail on credentials for — a submodule this project does not
+manage. A submodule that is already checked out is left exactly as it is, which
+keeps repeated runs cheap and offline-safe and never rewinds a tree someone
+parked on a particular commit; run `./config/pull` to float those. It depends on
+no pre-existing `config` submodule, so it works before `./config/pull` (which
+lives inside the `config` submodule) can. Claude Code runs it automatically via
+a `SessionStart` hook; other agents and humans run it by hand.
 
 ## Commit and history safety
 

README.md

@@ -21,6 +21,14 @@ as a Hugo Module. This repository does not invoke `embed-code` itself.
 2. [Go][go] `1.27.3` or newer (matches `site/go.mod`).
 3. [Node.js][nodejs] `18+`.
 4. [Hugo Extended][hugo-quick-start] in version `v0.169.0` or higher.
+5. [Dart Sass][dart-sass] in version `1.99.0` or higher. On macOS, install it with Homebrew:
+
+   ```shell
+   brew install sass/sass/sass
+   ```
+
+   Hugo looks for the `sass` executable on `PATH`. When Hugo finds it,
+   `hugo env` lists `github.com/sass/dart-sass/...` entries.
 
 ## Configuration
 
@@ -129,6 +137,7 @@ the [`AUTHORING.md`](AUTHORING.md) file.
 [go]: https://go.dev/doc/install
 [nodejs]: https://nodejs.org/en/download/current
 [hugo-quick-start]: https://gohugo.io/getting-started/quick-start/#step-1-install-hugo
+[dart-sass]: https://gohugo.io/functions/css/sass/#dart-sass
 [site-commons]: https://github.com/SpineEventEngine/site-commons
 [hugo-modules]: https://gohugo.io/hugo-modules/introduction
 [embed-code]: https://github.com/SpineEventEngine/embed-code/tree/embed-code-go