0006 · Deployment instructions and permission diagnosis

English is authoritative; Chinese reference .

Status: Prepared on docs/deployment-clarity from main ad0d939e123f9cf77263de503a6aa2bdb14bd831, following the deployment guide change . No commit, PR or remote configuration change has been made for this change.

Review selection: The owner selected independent acceptance review only. Requirements, plan and execution reviews are owner-waived, not passed.

Requirements

Make the deployment guide directly executable. Remove plan comparisons and instructions to delete the deployment environment reference. Give exact actions for enabling deployment, selecting the current main push run, rerunning it and confirming both uploads. Explain Cloudflare token permissions at the correct account or user scope, including the difference between a domain policy and an account policy. Keep the English and Chinese guides equivalent and provide the ignored Chinese acceptance handbook.

Plan and decisions

Edit the existing guide pair and reuse the current CI path. Preserve workflow, application and dependency files. No account changes, secret edits, publication or deployment are part of this documentation change. Official token and rerun instructions were checked on 2026-09-18; no dependency upgrade is involved.

Use the existing current-main push run for first publication or recovery when available, with a checked PR as the fallback. State the click path, matching commit, artifact and success message together. Keep normal releases and rollback in their existing sections instead of introducing another release mechanism.

Distinguish the first Cloudflare authentication error from subsequent Wrangler diagnostics. The pinned Wrangler 4.131.1 error handler logs the authentication error before calling whoami; the membership diagnostic can then emit its read-permission warning. The repository’s release wrapper only reports the failed site and completed uploads. The failing request was subsequently identified as the Workers subdomain lookup with authentication code 10000. Its documented accepted permissions include Workers Scripts Write, already present in the supplied token summary; the guide therefore checks the effective token, account scope and secret precedence rather than prescribing extra user permissions. The exact credential mismatch or restriction remains unverified.

Execution

Simplified deployment-switch setup and removed the plan/environment-removal detour. Rewrote step 7 around GitHub’s Code, Actions, rerun and job-log controls, with concrete workers.dev paths. Added account-policy search terms and access levels for Workers Scripts and Account Settings, separate personal-token diagnostic permissions, secret replacement instructions and a first-error-first troubleshooting sequence. Existing domain cutover and rollback guidance remains available.

The account-token route follows Cloudflare CI authentication . The token permission reference distinguishes account permissions from zone/user permissions; limiting a policy to a domain does not grant account-level Worker upload access. The guide does not claim that adding a membership permission alone fixes deployment.

Acceptance and migration

Local validation on 2026-09-18 used the existing Node.js 26.8.2, pnpm 12.4.1, Go 1.27.1 and Hugo Extended 0.166.0 pins. pnpm install --frozen-lockfile, pnpm tools:hugo, pnpm build and all six pnpm test:output checks passed. No dependencies or lockfiles changed. git diff --check passed. The ignored handbook is outside Hugo mounts; its filename and private paths are absent from the published output.

Browser checks with locally installed Chrome 153.0.8010.53 covered both languages at 1440px and 390px: guide/change pages load, all 11 guide sections exist, and wide tables remain in horizontal scrolling containers without whole-page overflow. After the final troubleshooting revision, pnpm build:logs and all six output checks passed again. Source checks covered 16 relative links across the four changed public documents. Representative desktop/mobile screenshots of steps 5 and 7 were inspected. Screenshots are local inspection material, not public attachments.

Acceptance review — passed (2026-09-18): An independent reviewer checked the uncommitted change from the baseline above: both deployment guides, this bilingual change record, and the ignored Chinese acceptance handbook. The review confirmed source and official-reference accuracy, equivalent EN/ZH instructions, reuse of the existing CI process, appropriate test/document scope, privacy, reproducibility and public/local separation. No blockers remained. Requirements, plan and execution reviews remain owner-waived.

No full application suite or deployment dry run was repeated for this documentation change. No external credential, upload, DNS or TLS verification is claimed.

No migration required: this change modifies guidance and its change record, with no dependency, configuration, data schema, route or deployment behavior change. Later credential corrections are operator actions described by the guide; a replacement token should be validated before the previous token is revoked. After committing, documentation rollback is a normal revert PR. Save the ignored local acceptance handbook before removing its worktree.