Skip to content

Maintenance and upgrades

How to validate changes, review Nimbus upgrades, and prepare for publication.

Updated View as Markdown

Maintain the site through small, reviewed changes. Keep Nimbus pinned to an exact version. Review upstream improvements before merging them. A passing build is necessary. It does not replace checks of the reading experience and agent exports.

Local setup commands are in the repository file README.md. Use the Development guide for development practices.

Validate a change

Run these commands after a completed site change:

npm run validate
git diff --check
git status --short

validate runs deployment guard and verification tests, content renderer tests, Astro checks, the production build, and content lint. The build comes before lint because Nimbus checks internal links against the generated route map. Review the changed source and output for unintended content or sensitive material.

For research-skill or schema changes, also run:

npm run test:research

This separate suite needs Python 3.10 or newer. It checks initialization, output contracts, evidence links, visuals, and read-only legacy compatibility in isolated fixtures. It is not part of the Node-based validate command or the production build. Keep the skill and its tests versioned together.

If lint reports a new page as missing, check its source path and sidebar entry. Run the full validation command to refresh route metadata before checking links. Do not suppress the broken link rule.

  • Check desktop and mobile layout, links, and horizontal overflow.
  • After interface changes, check keyboard use, reduced motion, sidebar controls, focus view, and the mobile drawer.
  • Check page Markdown exports after content or component changes.
  • After route changes, also check /llms.txt, /llms-full.txt, and page MDX exports.
  • Check search after changes to navigation, indexing, or dependencies.
  • Report existing warnings and unresolved failures.
  • Preserve unrelated changes.

A production preview provides the built search index.

For an additional structural and migration audit, run:

npx --no-install @cloudflare/nimbus-docs check --json

Review status, readiness, findings, and skipped checks. A successful exit code does not establish full coverage. Resolve errors and required work.

A partial check identifies a gap. It does not authorize you to ignore that gap. Do not repeatedly apply corrections when the remaining work needs user input or manual review.

Nimbus documents its check behavior. For request rendering, the production build remains a separate required check.

Review Nimbus upgrades

Package updates and updates to copied components are separate. migrate reviews package API changes. outdated and diff identify changes to starter files and registry components. Customized files may need manual merging. See the official upgrade workflow.

Use the installed CLI through npx --no-install. This prevents commands from silently downloading a different package version. Preserve package-lock.json. Preserve the exact Nimbus version in package.json.

  1. Establish a recovery point. Inspect the working tree. Preserve unfinished work. Use a reviewed backup or, if the user authorizes a commit, a Git checkpoint.
  2. Review the release. Inspect release notes, compatibility requirements, and the requested target version. Do not upgrade solely because a newer version exists.
  3. Update the dependency. Install the chosen exact version only after the user authorizes the upgrade. Review changes to the package file and lockfile.
  4. Preview migrations. Run the command below. Review every proposed edit, required review, and blocker before applying changes.
npx --no-install @cloudflare/nimbus-docs migrate --dry-run --diff
  1. Complete the reviews. Apply recognized safe migrations with migrate --yes only within the authorized upgrade. Merge customized code manually. Repeat the migration plan until you complete the required work. Then check the reviewed baseline.
  2. Review copied files. Run outdated. Then run diff for each relevant file. Use diff FILE --apply only for a reviewed clean update. Do not overwrite the logo, reading controls, source editor, or other custom work.
  3. Validate and check. Follow the validation checklist. Run the Nimbus structural check. Update these guides when development practices change.
npx --no-install @cloudflare/nimbus-docs outdated
npx --no-install @cloudflare/nimbus-docs diff

nimbus.json records provenance and lastReviewedNimbusVersion, the previously reviewed Nimbus version. Keep this record in version control. It does not pin the installed package version. Do not change it manually to bypass pending work.

If the baseline is missing, supply the known previously reviewed version with migrate --from VERSION. Incomplete migration work can produce a nonzero exit code. Record completion only after the actual review.

Before using add COMPONENT_SLUG --overwrite, review all affected files and dependencies for the registry replacement. Do not remove license notices.

Preserve a usable local site

Use port 4327. Keep development bound to loopback, which restricts the server to the local computer. Do not interrupt servers for other projects.

Development and build caches are separate to avoid stale JavaScript dependencies. Preserve this separation. If controls stop responding, check failed script requests before changing interaction code. Restart only this project’s server when needed.

Stop the development server before starting preview on the same port. Keep the source editor in development mode only. Never include it in preview or production.

Website analytics

Cloudflare Web Analytics measures browser page views and page performance through a JavaScript beacon.1 Real User Measurements (RUM) describes the measurements collected from browsers. The site uses the Cloudflare dashboard for this configuration, not a repository script.

Observed dashboard selection, October 11, 2026: automatic RUM for latentlit.com, excluding visitor data in the EU. Cloudflare documents this option as automatic injection outside the EU.2 Collection check: pending. The observed selection does not prove that the saved configuration collects data. Record configuration and collection checks separately.

To check collection:

  1. Open Web Analytics in the Cloudflare dashboard.
  2. Select latentlit.com.
  3. Open Manage site to check the saved option.
  4. Visit a public page from a region that the saved option includes.
  5. Check the browser’s Network panel for the beacon script.
  6. Check for a successful beacon POST to /cdn-cgi/rum or /cdn-cgi/rum/.
  7. Check recent page views in the dashboard after a few minutes.

These steps describe a proposed verification procedure, not a completed collection check. The beacon sends POST requests. A GET request to that endpoint is not a valid collection test.3 Do not send synthetic payloads to the endpoint. Use one installation method per page.3 Do not add a manual beacon when automatic injection already works.

A missing beacon can reflect EU exclusion or a browser blocker.23 Check the request context before concluding that analytics is inactive. Browser analytics does not measure agents that only fetch Markdown exports. Use request-level analytics for those requests, subject to the available plan.3 Changes to analytics settings require user authorization.

Prepare for publication

Publication requires separate user authorization. Request the intended production origin from the user. Set SITE_URL before building for that origin. Never invent a public domain. Never use the local default as a production URL.

Deployment checks

Set SITE_URL explicitly in the build environment. Use the actual public HTTPS origin without a trailing slash. The root .env.example contains a placeholder, not a deployment address. Local environment files remain excluded from version control.

To check the origin without building or uploading, run:

npm run check:deploy-origin

The check rejects missing values, noncanonical URLs, IP addresses, local hostnames, and reserved or example domains. A canonical origin contains only the scheme, hostname, and optional port. It contains no credentials, path, query, or fragment. The check does not establish domain ownership or availability.

For an authorized deployment, use npm run deploy. Its predeploy step checks the origin first. It then runs npm run validate before Wrangler can upload files. Either failure stops this workflow. Local development and ordinary validation retain the localhost default.

The approved production origin is https://latentlit.com. For an authorized release from an authenticated Cloudflare CLI session, run:

SITE_URL=https://latentlit.com npm run deploy

The Worker is named latent-light. Its custom domain is configured in wrangler.jsonc. The workers.dev address and version preview URLs are disabled so public references use the intended domain. Do not replace an existing domain binding or deploy to a different account without confirmation.

Direct Wrangler commands bypass these checks. Use the same origin check and full validation in any future automated deployment. Passing checks does not authorize publication.

Review the repository, history, pages, and assets for privacy and usage rights. Keep third party notices. Settle the licensing of original material before public release. Check canonical URLs, social images, agent links, and search.

The current configuration builds a static site. wrangler.jsonc serves dist/ with a 404 fallback. Before changing to request rendering, review the Astro adapter and Cloudflare configuration together. Do not reuse the static assumptions.

Obtain explicit user authorization for commits and pushes. When automatic deployment is active, authorization to push or merge into main also authorizes production publication. Permission to edit or validate files does not authorize a push or merge. Request separate authorization for manual deployment or changes to hosting settings.

Automatic deployment

GitHub validates changes. Cloudflare Workers Builds publishes the site. Use one production deployment system. Do not add a competing GitHub deployment workflow.

Automatic production deployment is active. It was verified on October 3, 2026, with commit 15841ae. Both Validate site and Workers Builds: latent-light passed. The live pages and agent exports matched the build. Desktop and mobile checks also passed.

The existing latent-light Worker is connected to by-liu/latent-light. An authorized push to main triggers validation in GitHub and deployment in Cloudflare. These systems run independently. The GitHub workflow does not need a deployment job. Cloudflare repeats validation before upload through npm run deploy.

Manage the connection through Workers & Pages → latent-light → Settings → Builds. Keep the Cloudflare GitHub App’s repository access limited to the intended projects. Do not grant access to all repositories. Cloudflare documents its GitHub integration.

Use these production settings:

Setting Value
Repository by-liu/latent-light
Production branch main
Root directory Repository root
Build command npm ci
Deploy command npm run deploy
Build variable SITE_URL=https://latentlit.com
Build variable SKIP_DEPENDENCY_INSTALL=1
Node version .node-version, currently 24.21.0
Preview builds Disabled

npm ci installs the committed dependency versions. npm run deploy performs validation and builds before upload. The postdeploy step then checks the public deployment. Avoid a second build command that repeats validation. Cloudflare supports these build settings and version and installation controls.

The workflow .github/workflows/validate.yml checks pull requests targeting main and pushes to main. It uses the same Node version and lockfile. It has no deployment credentials. Its action references use full commit identifiers. Do not use pull_request_target to execute untrusted changes. See GitHub workflow security guidance.

GitHub branch protection is not enabled as of October 3, 2026. Requiring the Validate site check before merging pull requests into main is a recommended safeguard, not a currently enforced rule. Enabling branch protection requires separate authorization. Use a branch and pull request for substantial changes. Inspect content and assets before authorizing publication. Passing automated checks does not establish factual accuracy or publication rights. Administrators can bypass branch protection unless enforcement also applies to administrators. Do not use a bypass for unreviewed work.

A failed validation stops upload. A failed public check occurs after upload and can leave the new version active. Inspect Cloudflare build logs and the live site. Use the authorized recovery procedure when necessary. The public check retries briefly for propagation. It checks page content against the build, agent exports, canonical URLs, and editor unavailability.

Check both results through the status icon beside the pushed commit in GitHub. The Validate site check confirms validation, not publication. The Workers Builds: latent-light check reports the Cloudflare build. Select its Details link for build information. Cloudflare also provides View build history at the bottom of the Worker’s Deployments tab. See the build status documentation.

If Cloudflare reports that the project is disconnected from its Git account, use Manage beside the Git repository to review the GitHub App’s repository access. Preserve access for other existing projects. Restore the connection before testing another authorized push. A previous green Validate site check does not establish that Cloudflare received that push.

After a successful release, check the public reading experience. For a manual repeat of the smoke check, retain the matching build:

SITE_URL=https://latentlit.com npm run verify:deployment

Keep preview builds disabled until their origins, permissions, and publication boundaries receive a separate review. Keep credentials in Cloudflare, not source files or pull request jobs. To pause automatic publication, disconnect the repository under the Worker’s Builds settings. Disconnecting Builds is a hosting change that requires authorization. Do not change the production domain or remove the Worker to pause publication.

Review before a public GitHub repository

Review every intended file, including untracked files. git diff alone does not show new files before the first commit.

  1. Check pages, repository documents, assets, and any existing Git history for private material and credentials.

  2. Check exclusions for environment files, dependency directories, build output, and local tool state. Keep only the reviewed root .env.example. Exclude local AWS credentials and state with the root /.aws rule. Check the exclusion without opening credential files:

    git check-ignore -v -- .aws
    git ls-files -- .aws

    The first command must report the ignore rule. The second command must return no tracked paths. An ignore rule does not remove files that Git already tracks. Do not force-add credential paths.

  3. Check media provenance and retain required license notices. Decide the reuse terms for original code, writing, and identity artwork separately.

  4. Run npm audit. Investigate each advisory and record its relevance to the installed version and deployment design. Do not apply automatic major downgrades.

  5. Complete the validation checklist. Record unresolved findings and pending decisions in docs/publication-readiness.md.

  6. Confirm the GitHub owner, repository name, and public visibility with the user.

  7. After commit authorization, stage only reviewed paths. Review the staged file list and diff before committing.

  8. After repository creation authorization, create an empty remote repository. Check its address and visibility before configuring the local remote.

  9. Push only after separate push authorization. Do not enable automatic deployment as part of repository creation.

Publishing the repository and publishing the site are separate actions. The repository can be prepared before selecting a production SITE_URL. private: true in package.json prevents npm package publication. It does not control GitHub visibility.

Check the first deployment

Before upload, check the built canonical URLs, social image URLs, sitemap, and agent links against the approved production origin. Local URLs must not remain in those public references. Check that production excludes the source editor.

After an authorized deployment, check these items at the public address:

  • Desktop and mobile layout, images, navigation, and theme switching
  • Search results and reading controls
  • /about/philosophy and its intended redirect
  • Previous content guidance links and their HTML, Markdown, and MDX redirects
  • An unknown route and its 404 response
  • /llms.txt, /llms-full.txt, and page Markdown and MDX exports
  • Canonical URLs, sitemap entries, and social image URLs
  • Absence of editor controls and the source editor API

Local checks do not establish that Cloudflare routes and public URLs work. Record those results after testing the deployed site.

Record a release and recover

After a successful deployment, record the source commit, Worker version, production origin, build commands, tool versions, and validation results. Keep credentials outside release records. Identify the last working version before each later deployment. The first deployment has no previous version to restore.

For an authorized rollback:

  1. Confirm the affected Worker and its Cloudflare account.
  2. Identify the specific previously working version and its source commit.
  3. Check that its embedded URLs match the intended public origin.
  4. Review any changes to bindings or external data since that version.
  5. Request authorization to restore that specific version.
  6. Open the Worker’s Deployments view in Cloudflare. Select that version’s menu and choose Rollback.
  7. Repeat the public deployment checks. Record the restored version and outcome.

Cloudflare rollback restores a deployed Worker version. It does not restore external data or change the source repository. See Cloudflare rollback documentation.

If no suitable version exists, prepare the reviewed source in a separate working directory. Rebuild with the approved production origin and repeat validation. Deploy that recovery build only after authorization. Do not erase local changes or reset the current working tree to recover a public deployment.

References

  1. Cloudflare, About Web Analytics. Checked October 11, 2026. ↩

  2. Cloudflare, Enabling Web Analytics, automatic setup and the EU exclusion option. Checked October 11, 2026. ↩ ↩2

  3. Cloudflare, Web Analytics FAQ, beacon methods, installation, blockers and client-side measurement. Checked October 11, 2026. ↩ ↩2 ↩3 ↩4

Navigation

Type to search…

↑↓ navigate↵ selectEsc close