Publish the documentation website

The owner approved a public documentation website on 6 October 2026. The GitHub repository stays private. The published site includes the documentation, search index, diagrams and their text/JSON exports; anyone can read these without signing in.

Cloudflare hosts a copy of the static build. Serving it does not depend on the Mac, Shipyard or a home-network tunnel. Application credentials, private runtime state and repository tooling are not deployed.

Publication status

The public site is akshat-dev-environment.pages.dev. The first manual production deployment passed on 6 October 2026, including browser checks of the homepage, search and an interactive diagram. The initial upload used source commit 9be167f from the hosting PR.

Automatic publishing passed on 6 October 2026 after PR #4 merged. GitHub run 37487128827 tested, built and published commit 4297cc0 using the dedicated CI token. Cloudflare recorded a matching production deployment, and the public site served the merged content. Future merges to main use the same workflow.

Normal updates

1. Submit a PR using the contribution checklist. Since the site is public, review changed pages, diagrams and generated data for information suitable for publication.
2. CI runs the existing tests and build, including inventory consistency and local-link checks. PRs do not publish a preview.
3. After merge to main, the same workflow rebuilds and publishes dist/ only if all preceding checks pass. A manual workflow run on main can retry publication.
4. Check the published homepage, a changed page, search and any affected diagram. A successful upload does not replace checking the live site.

The workflow uses the pinned documentation Node version and Wrangler 4.147.0. Overlapping runs for the same branch are cancelled so an older build does not normally replace a newer one. Cloudflare deployment records identify the source commit.

Deployment configuration

Settings live in the private GitHub repository’s Actions secrets and variables:

• CLOUDFLARE_API_TOKEN (secret): Cloudflare Pages Edit permission for the publishing account.
• CLOUDFLARE_ACCOUNT_ID (variable): account containing the Pages project.
• CLOUDFLARE_PAGES_PROJECT (variable): exact Pages project name.
• DOCS_SITE_URL (variable): canonical public URL, supplied as SITE_URL during build.

Never put the API token in Git, documentation or chat. Use a dedicated CI token restricted to the intended account. Local manual publishing uses the owner’s Wrangler login; CI uses its separate token. Rotating the CI token means updating the repository secret and rerunning the workflow.

Local preview remains available with the README commands. SITE_URL is optional locally; without it the preview uses its local routes and omits the sitemap.

Manual publication

From a clean checkout of the intended source revision, use the pinned documentation runtime and your local Wrangler login:

npm test
SITE_URL=https://akshat-dev-environment.pages.dev npm run build
npx --yes wrangler@4.147.0 pages deploy dist --project-name=akshat-dev-environment --branch=main --commit-hash="$(git rev-parse HEAD)"

Run each step only if the previous one succeeds. This publishes that checkout to the production URL, even when its Git branch is not main; normally publish merged main. Do not upload the repository root.

The existing project needs no creation step. During initial setup, Wrangler 4.147.0 tried to redirect project creation to Workers. Creating with pages project create akshat-dev-environment --production-branch=main --force selected Pages directly. Subsequent uploads to the existing project succeeded without that option.

Recover a failed publication

• Tests or build failed: fix the reported problem in a PR. Nothing from that run is published; the previous successful site remains available.
• Missing setting or authorization error: check the named repository settings, token validity and account/project match. Do not print token values or copy a local OAuth token into CI.
• Upload succeeded but content appears old: compare the deployment commit with the intended main commit and confirm that the URL is the production project URL. Check a changed page before changing cache settings.
• Wrong content is live: roll back to the previous successful production deployment in Cloudflare, then fix or revert the source through a PR. The next successful main publication replaces a dashboard rollback.

A direct-upload project uses this workflow rather than Cloudflare’s Git integration. Use the Cloudflare CI guide for credential setup and the rollback guide for recovery.