Maintenance and upgrades

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, Astro checks, content lint, and the production build. Review the changed source and output for unintended content or sensitive material.

If lint reports a new page as missing, check its source path and sidebar entry. If both are correct, run npm run build to refresh route metadata. Then repeat validation. 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

5. 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.
6. 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.
7. 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.

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.

The repository contains the validation workflow. The Cloudflare connection still needs browser setup. Do not describe automatic deployment as active until the connection and first build pass.

Connect the existing latent-light Worker to by-liu/latent-light through Workers & Pages → latent-light → Settings → Builds → Connect. Authorize the Cloudflare GitHub App for this repository only. Do not grant access to all repositories. Cloudflare documents its GitHub integration.

Use these production settings:

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.

Require the Validate site check before merging pull requests into main. 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.

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.
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
• 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.