[0carespal]

Fixes openclaw/openclaw#196183

Problem

Search on docs.openclaw.ai showed "Search is unavailable" after Pagefind moved from 1.5.2 to 1.6.0. The Pagefind entry and worker were served from the fixed paths /pagefind/pagefind.js and /pagefind/pagefind-worker.js with Cache-Control: public, max-age=31536000, immutable. Browsers and edges that had cached the 1.5.2 runtime kept using it against the 1.6.0 index, and search failed. Since the file names carry no version, the cached copies could not be invalidated.

Fix

• Version the assets. New scripts/docs-site/pagefind-assets.mjs reads the installed Pagefind version and exposes the output dir pagefind/v<version>. New pagefind-build.mjs writes the index, entry and worker there, and docs:build calls it instead of the bare pagefind command. site-js.mjs loads /pagefind/v<version>/pagefind.js, so every Pagefind upgrade gets new URLs.
• Fail the build on a mismatch. pagefind-normalize.mjs reads the versioned entry and throws if its version differs from the installed runtime.
• Let old copies expire. The legacy unversioned pagefind.js and pagefind-worker.js now get the short mutable cache policy in r2-prepare.mjs (R2 metadata) and workers/docs-router.ts (isMutableStaticPath). Versioned assets keep the immutable policy, which is safe because their URL changes with the version.
• Smoke check. smoke.mjs now requires the versioned pagefind.js, pagefind-worker.js and pagefind-entry.json.

Tests

• pagefind-cache.test.mjs (new): a Playwright regression that warms a browser with the old 1.5.2 entry and worker under the immutable policy, then checks that search works against the current build and requests a worker outside the old cache key. The real 1.5.2 worker used for this is in test-fixtures/pagefind-1.5.2/ with its license.
• r2-upload.test.mjs and docs-router-dotted.test.mjs: assert the cache policy for legacy vs versioned paths.
• publication-stability.test.mjs and analytics-behavior.test.mjs: updated for pagefind-build.mjs and the versioned path.

Validation

• Full R2 build passed; versioned and legacy Pagefind cache metadata checked:
  [paste the cacheControl values for the pagefind keys here]
• npm run docs:smoke passed
• Pagefind warm-cache browser regression passed
• Publication stability, analytics, worker routing and R2 upload suites passed

Not run locally: the rest of the full suite on my Windows machine (WebKit, symlink permissions, bash-dependent tests, one Windows path assertion), which fail for reasons unrelated to this change. I'm relying on CI for those.

AI assistance

I wrote the fix. I used Codex to help run the test suites and push the branch.