| name | educates-upgrade-theme-libraries |
| description | Upgrade the vendored third-party frontend libraries bundled into the Educates workshop dashboard theme (Bootstrap, Font Awesome, jQuery, Underscore.js, JSONForm, js-yaml). Invoke when asked to "update theme libraries", "upgrade bootstrap/font-awesome/jquery/underscore/jsonform/js-yaml", "bump the dashboard frontend libraries", or "refresh the vendored web assets". |
| argument-hint | [<library-name>] (omit to check/update all six) |
| allowed-tools | Read, Bash, WebFetch, Glob, Edit |
Educates Workshop Theme Libraries Upgrade Protocol
Refresh the third-party browser libraries vendored into the workshop dashboard
theme. These assets are committed directly into the repository and have no
build-time fetcher — this skill is how they are updated: it re-downloads a
library from its upstream source and writes the files back into the tree.
If $ARGUMENTS names a specific library (e.g. bootstrap, jquery), update
only that one. With no argument, check all six for newer upstream versions and
report what's available before changing anything.
Canonical location
All libraries live under one directory (the educates dashboard theme's static
assets):
workshop-images/base-environment/opt/eduk8s/etc/themes/educates/static/static/libraries/
Call this $LIB below. The target filenames are version-agnostic (no
version in the path), so an upgrade overwrites the existing files in place — no
renaming or git rm of old files is needed (except Font Awesome / Bootstrap if
upstream ever changes which files ship).
Libraries, sources, and target files
Two shapes: zip subset (download a release zip, extract a few files,
stripping the zip's top-level folder) and single file (download one JS file
directly). Versions shown are the current committed ones — confirm against the
tree before bumping (see "Finding current versions").
| Library | Shape | Upstream source (version in URL) | Files written under $LIB |
|---|
bootstrap | zip subset | https://github.com/twbs/bootstrap/releases/download/v<VER>/bootstrap-<VER>-dist.zip | bootstrap/css/bootstrap.min.css, bootstrap/js/bootstrap.bundle.min.js |
font-awesome | zip subset | https://github.com/FortAwesome/Font-Awesome/releases/download/<VER>/fontawesome-free-<VER>-web.zip | font-awesome/css/all.min.css + font-awesome/webfonts/{fa-brands-400,fa-regular-400,fa-solid-900,fa-v4compatibility}.{woff2,ttf} (8 webfonts) |
jquery | single file | https://cdn.jsdelivr.net/npm/jquery@<VER>/dist/jquery.min.js | jquery/jquery.min.js |
underscore | single file | https://cdn.jsdelivr.net/npm/underscore@<VER>/underscore-umd-min.js | underscore/underscore-umd-min.js |
jsonform | single file | https://cdn.jsdelivr.net/npm/jsonform@<VER>/lib/jsonform.min.js | jsonform/jsonform.min.js |
js-yaml | single file | https://cdn.jsdelivr.net/npm/js-yaml@<VER>/dist/js-yaml.min.js | js-yaml/js-yaml.min.js |
For the two zip-subset libraries, only the files listed above are kept; the
rest of the release archive is discarded.
Keep aligned with the renderer and gateway apps
These same libraries are also npm dependencies of the two bundled apps in the
base environment — workshop-images/base-environment/opt/renderer and
.../opt/gateway — which compile them into their own JavaScript via esbuild.
The vendored theme copy and the npm-bundled copy must stay on the same
version, or the dashboard's static assets drift from what the apps ship.
Whenever you change a vendored library version here, update the matching npm
dependency in each app's package.json that declares it, and vice versa:
| Theme library | npm package | renderer/package.json | gateway/package.json |
|---|
bootstrap | bootstrap | yes | yes |
font-awesome | @fortawesome/fontawesome-free | yes | yes |
jquery | jquery | yes | yes |
js-yaml | js-yaml | yes | yes |
underscore | underscore | yes | — |
jsonform | jsonform | yes | — |
The package.json versions are caret ranges (e.g. "bootstrap": "^5.3.2").
Set the range to the version you vendored (^<VER>), then refresh the lockfile
and rebuild so the bundle matches:
cd workshop-images/base-environment/opt/<app>
npm install
The app bundle is produced by scripts/compile.sh (tsc + esbuild); it runs
during the base-environment image build, so a make image-base-environment (or
running compile.sh in the app dir) is what proves the new version compiles and
bundles cleanly.
Finding current versions
The committed minified files carry a version banner in their first line(s):
LIB=workshop-images/base-environment/opt/eduk8s/etc/themes/educates/static/static/libraries
head -c 200 "$LIB/bootstrap/css/bootstrap.min.css"
head -c 120 "$LIB/jquery/jquery.min.js"
head -c 200 "$LIB/font-awesome/css/all.min.css"
head -c 200 "$LIB/underscore/underscore-umd-min.js"
head -c 200 "$LIB/js-yaml/js-yaml.min.js"
head -c 200 "$LIB/jsonform/jsonform.min.js"
Finding the latest upstream version
- bootstrap: latest release at
https://github.com/twbs/bootstrap/releases (use the latest stable v5.x, not a beta/alpha).
- font-awesome: latest "Free for Web" release at
https://github.com/FortAwesome/Font-Awesome/releases (the asset named fontawesome-free-<ver>-web.zip).
- jquery / underscore / jsonform / js-yaml: the npm version. Check
https://www.npmjs.com/package/<name> (or https://registry.npmjs.org/<name>/latest). jsDelivr serves any published npm version at the URL pattern above.
Use WebFetch to read the releases/npm page and pick the latest stable version. For major-version bumps, read the changelog for breaking changes and flag them to the user before proceeding.
Update process
Set up the path and a scratch dir:
LIB=workshop-images/base-environment/opt/eduk8s/etc/themes/educates/static/static/libraries
TMP=$(mktemp -d)
Single-file libraries (jquery, underscore, jsonform, js-yaml)
Just overwrite the file from the versioned jsDelivr URL. Example (jquery → <VER>):
curl -fsSL "https://cdn.jsdelivr.net/npm/jquery@<VER>/dist/jquery.min.js" -o "$LIB/jquery/jquery.min.js"
Use the matching URL + target from the table for underscore, jsonform, js-yaml. Always use curl -f so a 404 (bad version/path) fails loudly instead of writing an error page into the asset.
Zip-subset libraries (bootstrap, font-awesome)
Download the release zip, then copy only the listed files, stripping the zip's
top-level folder. Bootstrap example (<VER> e.g. 5.3.8):
curl -fsSL "https://github.com/twbs/bootstrap/releases/download/v<VER>/bootstrap-<VER>-dist.zip" -o "$TMP/bootstrap.zip"
unzip -q "$TMP/bootstrap.zip" -d "$TMP/bootstrap"
ROOT="$TMP/bootstrap/bootstrap-<VER>-dist"
cp "$ROOT/css/bootstrap.min.css" "$LIB/bootstrap/css/bootstrap.min.css"
cp "$ROOT/js/bootstrap.bundle.min.js" "$LIB/bootstrap/js/bootstrap.bundle.min.js"
Font Awesome example (<VER> e.g. 6.5.1):
curl -fsSL "https://github.com/FortAwesome/Font-Awesome/releases/download/<VER>/fontawesome-free-<VER>-web.zip" -o "$TMP/fa.zip"
unzip -q "$TMP/fa.zip" -d "$TMP/fa"
ROOT="$TMP/fa/fontawesome-free-<VER>-web"
cp "$ROOT/css/all.min.css" "$LIB/font-awesome/css/all.min.css"
for f in fa-brands-400 fa-regular-400 fa-solid-900 fa-v4compatibility; do
cp "$ROOT/webfonts/$f.woff2" "$LIB/font-awesome/webfonts/$f.woff2"
cp "$ROOT/webfonts/$f.ttf" "$LIB/font-awesome/webfonts/$f.ttf"
done
Before copying, ls "$ROOT/css" "$ROOT/webfonts" to confirm upstream still ships
these exact filenames; Font Awesome occasionally changes its webfont set across
major versions. If the set changed, update the table and the file list, and
git rm any file no longer shipped so stale assets don't linger.
Clean up: rm -rf "$TMP".
Verification
- Each updated file is non-empty and carries the new version banner:
head -c 200 "$LIB/<library>/<file>"
Confirm the version string matches what you intended (catches a silently
downloaded error page or a wrong path).
- The downloaded file is the minified asset, not HTML (a 404 page).
file or a
quick head should show JS/CSS/font content, not <!DOCTYPE html>.
git diff --stat shows the expected files under $LIB/<library>/ and,
when the version changed, the matching package.json (+ package-lock.json)
in renderer/gateway — see "Keep aligned with the renderer and gateway
apps". A theme-only change with no package.json update is usually a drift bug.- Full check (optional, heavy): rebuild the base environment image so the theme
bundles the new assets:
make image-base-environment
then load a workshop and confirm the dashboard renders (no missing-asset 404s
in the browser console).
Notes and gotchas
- These files are committed to git, so the update IS the change — there's no
separate sync step or lock file to regenerate.
- The libraries are not checksum-pinned; integrity rests on HTTPS plus the
version-banner and not-HTML checks in Verification above.
- Keep the target filenames exactly as listed — the theme's HTML/templates
reference them by these stable names (e.g.
jquery.min.js,
bootstrap.bundle.min.js, underscore-umd-min.js).
- This skill only covers these six dashboard frontend libraries; it does not
touch base-image CLI tools (helm, yq, hugo, …) or any other software.
Post-upgrade checklist
