Development guide

English is authoritative; Chinese reference . This maintained guide covers reusable local setup, development and verification. Each change also has a Chinese-only, ignored checklist under .local/acceptance/; durable results belong in its public change log.

1. Open the feature worktree

These commands target macOS with zsh. New changes use their own directory and branch from the workflow . Replace new-feature-name in the example. From the canonical main/ directory:

git worktree add -b feat/new-feature-name ../new-feature-name main
cd ../new-feature-name
git branch --show-current

Expected branch: feat/new-feature-name. Run subsequent commands from this directory, which contains package.json. Use a sibling worktree for changes; the same setup can be used to inspect approved main locally.

2. Install the pinned environment once

Before installing or switching tools, record node --version, pnpm --version and go version (note “not installed” for missing commands). Keep the previous versions available for recovery; when upgrading an existing environment, first read that change’s migration assessment in its log and local checklist.

Node.js: if you already use nvm, run the following in this terminal. Repeat nvm use 26.8.2 in each new terminal; a version file does not switch Node automatically.

nvm install 26.8.2
nvm use 26.8.2
node --version

If nvm is installed but not loaded, load it with . "${NVM_DIR:-$HOME/.nvm}/nvm.sh". Without a version manager, install the macOS .pkg from the Node.js 26.8.2 release , reopen the terminal and confirm v26.8.2. See nvm usage for an existing nvm installation.

pnpm: install the exact package into a user-owned prefix and add its executable directory to this terminal’s PATH:

npm install --global --prefix "$HOME/.local" pnpm@12.4.1
export PATH="$HOME/.local/bin:$PATH"
pnpm --version

Expected: 12.4.1. Add the same export PATH line once to your shell configuration if you want it available in new terminals. npm only bootstraps pnpm here; use pnpm for every project install and command. The official package pins the platform binaries too.

Go: run go version. If it already reports go1.27.1, skip installation. Otherwise select the matching macOS package under Go 1.27.1 downloads : darwin-arm64.pkg for Apple Silicon, darwin-amd64.pkg for Intel. Follow the official installer steps , reopen the terminal and confirm the version. uname -m identifies arm64 or x86_64.

3. Install project dependencies

pnpm install --frozen-lockfile
pnpm tools:hugo
.cache/hugo/hugo version

The first command uses the existing lockfile; the second downloads and checks Hugo Extended 0.166.0 into ignored .cache/hugo/. Its version output must include v0.166.0 and +extended. Do not install Astro, TypeScript or Wrangler separately; they are locked project dependencies. First-time log startup/build also downloads OINK through Go.

Local browsing needs no .env, Cloudflare account, token or domain. .env.example only documents optional canonical URLs; production setup is separate. Installation requires access to the official package/release and Go module hosts.

4. Start, inspect and stop both sites

In terminal A, from the feature root with the pinned Node/pnpm active:

pnpm dev --host 127.0.0.1 --port 4321

Open http://127.0.0.1:4321/ for Fieldnotes; Chinese is /zh/. Projects and Experience use /projects/ and /experience/, with Chinese under /zh/. In terminal B, enter the same feature root, activate the same environment, then run:

pnpm dev:logs

Open http://127.0.0.1:4322/; Chinese is /zh/. These are separate development servers with file watching. Keep their terminals open. Press Ctrl+C in each terminal to stop each server. If a port is occupied, stop the earlier server before retrying; use the URL printed by the command.

Reusable manual checks:

• Portfolio: inspect Home, Projects, a project detail and Experience; switch EN/ZH on a project and confirm the equivalent page. There is no Research tab or comparison/demo page.
• Layout/accessibility: inspect a narrow viewport, use Tab and the skip link, and enable the OS/browser reduced-motion preference. Check readable content, visible focus and no horizontal page overflow.
• Logs: open change articles, the README and guides; switch languages, follow document links, and search for a term present in a change article in each language.
• Content editing: follow the content guide to add a temporary EN/ZH Markdown pair. It should appear without component edits. Remove the temporary pair afterward. Draft/publication validation and production 404 are checked in step 5.

5. Run checks and inspect production output

pnpm verify runs the complete suite. Browser checks fulfill requests directly from both static builds, including OINK search; no HTTP listener or running development server is required.

pnpm exec playwright install chromium
pnpm verify
pnpm deploy:dry-run

Playwright’s browser download is only needed on first setup or a browser-version upgrade. On Linux CI, use pnpm exec playwright install --with-deps chromium instead.

Expected: type checks, unit tests, both static builds, output tests, desktop/mobile browser tests and real content-build fixtures pass. Fixtures prove that new translated content creates routes, drafts disappear and missing translations/unsafe slugs fail real builds. Browser tests cover language targets, keyboard focus, reduced motion, layout, 404 and English/Chinese OINK search. Both Wrangler dry runs must succeed without uploading; no Cloudflare login is required for dry run.

For manual inspection of the built files, after pnpm verify, run these in separate terminals:

node scripts/serve-static.mjs dist/portfolio 4310

node scripts/serve-static.mjs dist/logs 4311

Open http://127.0.0.1:4310/ and http://127.0.0.1:4311/. On the portfolio, /not-a-page/ must return HTTP 404 with EN/ZH recovery links. Production previews serve the last build; rebuild after changes. Stop each with Ctrl+C. This local server is a review tool; deployed static pages do not require a Node application server.

6. Troubleshooting and delivery boundaries

• Version/engine mismatch: run node --version, pnpm --version, go version and command -v node pnpm go; correct the selected versions/PATH instead of weakening version checks or regenerating the lockfile.
• Missing Hugo: run pnpm tools:hugo. If a trusted system certificate is required for a download, try NODE_USE_SYSTEM_CA=1 pnpm tools:hugo; do not disable TLS verification.
• Missing browser executable: run pnpm exec playwright install chromium. If a manual preview port is occupied, stop its earlier process before starting another preview.

Inspect intended source/config/docs/lockfile changes, EN/ZH meaning, exact pins and privacy. Generated files, caches, .env and browser traces remain ignored. Follow the workflow for each change’s local checklist, durable acceptance/migration evidence, selected reviews and commit confirmation.

GitHub required-check/PR enforcement, production credentials, Cloudflare uploads/routing/DNS and live URLs remain pending until authorized deployment setup . Local acceptance does not prove hosted behavior.