devlog: docs, workflows, and the finish line

this is the “make it real” commit. everything that was on the todo list under “before
you can call this a real project” happened in one sitting.

docs site

built a full docs site using docmd. lives in Docs/ with its own package. seven pages
covering everything: home/landing page, quickstart guide, core concepts explainer, and
individual reference pages for the client library, github action, worker, hot-swap
internals, manifest format, and download metrics.

the client library page has full config tables, event references, api docs for every
public method, and the UpdateNotification component. the action page documents every
input and shows what the cdn branch looks like after a deploy. the worker page covers
both endpoints, version comparison logic, caching, and rate limiting.

the hot-swap page explains how each asset type gets replaced: scripts via dom
replacement with data-hot-file tagging for subsequent updates, css via
CSSStyleSheet.replaceSync and adoptedStyleSheets (which is CSP-safe), and images
via base64 data uris.

used the “sky” theme with system dark mode toggle. search, sitemap plugin, code
highlighting, all enabled.

github pages deployment

new workflow at .github/workflows/static.yml. builds the client library, builds the
demo, builds the docs, then assembles them into a single pages-root/ directory. demo
goes under /demo/, docs go at the root. deploys to gh-pages with
peaceiris/actions-gh-pages.

npm publish workflow

.github/workflows/release-npm.yml. triggers on github release publish or manual
dispatch with a dry-run option. builds the client library, strips private, scripts,
and devDependencies from package.json, copies in the readme and license, then
publishes with --provenance. also removed "private": true from Build/package.json
so npm will actually accept it.

security audit workflow

daily cron job plus on-push when lockfiles change. runs npm audit --audit-level=high
across every package (root, Build, Worker, Action, Demo, Docs). all the audit steps
have || true so the workflow reports issues without failing the build, which felt
like the right balance for now.

separate test workflow

split the test job out of ci.yml into its own .github/workflows/test.yml. same
matrix across node 20 and 22, runs jest in all three packages. keeps the ci workflow
focused on lint and build.

todo status

checked off docs. what’s left: update the readme with better examples, maybe attach
the worker to a custom domain, and publish to npm. the npm workflow is ready, just
need to actually pull the trigger.