quern.dev

Landing page, docs site, and update-check endpoint for Quern.

Astro + Starlight for the pages, a small Cloudflare Worker (src/worker.js) for the API routes and asset serving.

Cloudflare is connected to this GitHub repo and builds and deploys on every push to main. That connection is configured in the Cloudflare dashboard, not in this repo — there is no workflow file and nothing in wrangler.toml that hints at it. Treat a push to main as a publish.

There is no manual step. If you ever need one — the Git integration is disconnected, or you want to ship without a commit:

npm run build
CLOUDFLARE_API_TOKEN="$(cat quern-analytics/cloudflare-api-token.txt)" npx wrangler deploy

That path needs an account ID as well: the deploy token is scoped without account-list permission, so wrangler cannot work out which account to target on its own. Prefer pushing.

To sanity-check what is actually live:

curl -s https://quern.dev/api/check-update?sha=$(git -C ../quern rev-parse origin/release/stable) | python3 -m json.tool

update_available is only ever true when the client sends sha=; omitting it answers false regardless of channel, which reads like a bug and is not one.

The channel is taken from channel= when the client sends it, and otherwise inferred from a prerelease suffix in version=. Clients older than v0.14.1 send neither channel= nor anything else that identifies the channel except the version string, so without the inference a beta user is compared against release/stable and told to install an older version. Those clients cannot be fixed by shipping a new quern, because the broken check is what would have told them to upgrade.

Everything under src/content/docs/ is a derived copy of docs/guides/*.md in the quern repo. Edit the guide there, then sync:

scripts/sync-docs.py                 # rewrite the site pages from ../quern
scripts/sync-docs.py --check         # report drift, exit 1 (for CI)
scripts/sync-docs.py --repo /path/to/quern

The transform: the repo guide supplies the body, the site page keeps its own Starlight frontmatter (the title and description drive the sidebar and meta tags), and relative foo.md links become absolute routes /section/foo/.

Editing a page under src/content/docs/ directly will work until the next sync overwrites it. These pages went unsynced from March to August 2026, during which the app-state page told readers that checkpoints could not capture the keychain — months after that stopped being true. --check exists so that gap is visible instead of silent.

src/pages/index.astro is the landing page and is not generated — edit it directly. It carries claims that go stale (the tool count, the Node version floor); the numbers of record live in the quern repo's README and mcp/package.json.

npm install
npm run dev          # astro dev — pages only, no worker
npx wrangler dev     # full worker + built assets; run npm run build first
npm run build        # → dist/