0003 · Website foundation

Bilingual static portfolio, Markdown content, public engineering logs, tests and release configuration.

English is authoritative; Chinese reference .

Status: local verification and final acceptance review passed; owner manual review pending. Base: ee17e58; branch: feat/website-foundation; sibling worktree: ../website-foundation. No remote or PR exists yet.

Current review selection: the owner requires only the final acceptance review for the remaining work; execution review is waived. Requirements and plan reviews already completed apply to their recorded scopes. The final review checks correctness, first-principles simplicity, test/document value and privacy. Delivery is prepared for owner manual review; commit preview and confirmation remain required.

Current documentation delivery: permanent guides and public PR logs remain bilingual; the mandatory per-change acceptance handbook is Chinese-only, local and ignored. The P1 plan below records its originally reviewed scope; the Execution and Acceptance sections describe the delivered structure.

Requirements

The objective is a runnable, maintainable engineering foundation. Final visual design, real biography/projects/experience, blog consolidation and production publication are excluded from this change.

ID	Acceptance requirement
F01	Build the portfolio as static Astro with TypeScript and pnpm. Provide English `/` and Chinese `/zh/`, translated navigation, language switching, Projects list/detail pages, Experience and a useful 404. No Research tab or request-time application server. Use a restrained responsive shell; final art direction and elaborate animation are separate work.
F02	Manage projects and experience through Markdown with validated metadata. Adding an entry must not require editing page components. Published entries require matching translations; invalid metadata, unsafe/duplicate routes and inconsistent publication state must fail checks. Drafts must be absent from production routes, indexes and generated public content. Use clearly labeled neutral demonstration content, never invented personal achievements.
F03	Build a separate static public log site using Hugo/OINK, with English and Chinese navigation, usable search and one complete article per change. Reuse repository log sources; resolve article, guide and language links in generated output without maintaining duplicate editable content. Existing records and this change must be browsable.
F04	Verify latest stable direct dependencies and tools from official sources, pin exact versions, commit generated lockfiles and freeze CI installs. Record versions/date/sources in this article. Pin Git dependencies and CI Actions to full release commit SHAs. Ask the owner about compatibility exceptions; do not silently choose older releases.
F05	Include meaningful automated positive/negative content tests, generated-route/draft checks and browser coverage for language navigation and responsive accessibility basics. Type checks and both production builds must pass. Record actual commands/results; distinguish local verification from pending hosted checks.
F06	Provide a simple CI/CD configuration: PR checks before merge; recheck main after merge; deploy the checked artifacts automatically only from main after success. PR jobs receive no deployment secrets. Serialize production uploads and reject stale reruns immediately before upload; do not cancel uploads already started. Report partial failure because the two sites do not deploy atomically.
F07	Prepare two Cloudflare Workers Static Assets configurations and deployment instructions. Do not publish, create remote resources, change DNS, replace a live website, or fabricate repository/PR metadata. Remote rules must later enforce PR-only integration and required checks; workflow files alone do not enforce this.
F08	Update concise bilingual README, contributor/workflow guidance, content instructions and acceptance steps to match the delivered foundation. Keep Apache-2.0 and third-party attribution. Use relative repository references and exclude private data, secrets, workstation paths and raw sessions from public content/evidence.

Owner decisions already fixed: engineering foundation only; all four reviews; pnpm; English primary/Chinese reference; independent public OINK site; Cloudflare static hosting; PR-only integration with automatic deployment after passing checks. External account/repository/domain settings remain pending before production activation.

Requirements review

2026-09-13 — foundation_requirements_review: PASS, no blockers. Scope: R1 overview authorization and the Requirements section in both languages, ending before this review heading. Confirms measurable foundation scope, proportional complexity and privacy. This pass permits planning only.

Plan and decisions

Tools and commands. Add the exact package manifest/lockfile, Node/Go/Hugo version files, pnpm exact-save settings and ignore rules for generated output/tool caches. Keep application code at src/; one package manages the portfolio, tests and deployment CLI. Use the Node test runner for units and Playwright for browser tests. Install pinned local tools without changing global tool versions.
Content and routes. Use Astro’s built-in Markdown collections and Zod metadata schemas, with file-derived unique loader IDs. A small shared content validator checks safe slugs, duplicate routes, required translation pairs and matching draft state before selecting published entries. Generate localized static routes from shared components; keep language copy in one typed dictionary. Provide labeled example project/experience pairs and a harmless draft pair used to prove exclusion. Use semantic HTML, visible keyboard focus, responsive CSS and reduced-motion support; no React, MUI, Three.js or MDX plugin is needed for this foundation.
OINK logs. Use a Hugo site under log-site/ and the pinned OINK release commit. Mount repository logs/ and docs/ into the content tree along with the root contributor documents, preserving their relative path relationships. Add only the needed bilingual home/section pages. Use a narrow Markdown link hook if needed to resolve source .md and .zh.md links to generated translated pages; fail on unresolved repository references. Enable OINK’s local search and minimize unused outputs/features. Publish to dist/logs/; Astro publishes to dist/portfolio/. Retain theme attribution and its supplied third-party notices.
Checks. Unit-test valid content, unsafe slugs, duplicate translation/route keys, missing translations, mismatched drafts and deployment decisions (current head, stale rerun, API failure, upload failure). Run type checks, both production builds, and output checks proving expected EN/ZH routes and no draft sentinel in public artifacts. Browser-test desktop and narrow mobile layouts, keyboard navigation/focus, language switching with equivalent page targets, 404 behavior, local links and OINK search results; check reduced-motion behavior. Include one real invalid-content build check to prove validation is connected to the build. Validate both Wrangler configurations with local dry runs only.
CI/CD. Add one GitHub workflow with checks and deploy jobs. PRs and pushes to main run frozen installs, checks/tests and both builds; successful main runs upload the same tested static output for the deploy job. Deployment requires one-time external configuration, a push to main, successful checks and a production environment. Use pinned Actions and read-only repository permissions; expose Cloudflare secrets only in deployment. A non-cancelling production concurrency group serializes releases. Inside the lock, re-read main’s head immediately before starting the two-site upload; skip stale runs and fail closed on verification errors. Once release upload begins, finish its ordered uploads without cancellation; a failed upload fails the release and reports any already-published site. This prevents an old rerun replacing a newer deployment without building a separate release service.
Deployment configuration and guides. Add two assets-only Wrangler configurations, each with custom 404 handling and no Worker handler/adapter. Provide a concise bilingual content guide, deployment/setup guide and acceptance handbook. External setup must define real repository/Worker names, HTTPS site URLs, credentials and PR/check rules; production activation stays disabled until explicitly configured. No account IDs, tokens, guessed domains, remote creation or live publication in this change. Document inspection of externally enforced rules and rollback to a deliberately selected known-good revision through an authorized PR, not a stale pipeline rerun.
Closeout. Run the execution review before writing actual acceptance results, then run the acceptance review against the handbook/evidence. Update README/AGENTS status for the implemented foundation; preserve earlier logs as dated records and link to this change. Stage only intended source/config/docs/lockfiles, inspect the full diff, and request confirmation of the complete commit preview.

Simplification choices: Astro’s collections and static rendering replace a CMS/backend; plain CSS and shared localized components cover the foundation. Hugo is present because the owner selected OINK; mounts avoid a content synchronization service. Node’s built-in runner avoids another unit-test framework. One CI workflow and a small testable deployment command avoid a separate release orchestrator. Generated files and local tool caches remain ignored.

Compatibility decision: the owner approved TypeScript 6.0.3, the newest stable 6.x release, because the latest @astrojs/check declares support for TypeScript 5/6 while the newest TypeScript release is 7.0.2. Other selected direct dependencies/tools use their latest stable releases. This exception is specific to TypeScript, not a blanket waiver.

Verified versions

Verified on 2026-09-13 using official registry/release metadata; repeat compatibility checks during installation. Dependency manifests will contain exact versions, and generated lockfiles fix transitive resolutions.

Dependency/tool	Selected release	Official source
Astro	7.3.2	Registry
Astro check	0.9.10	Registry
TypeScript	6.0.3, owner-approved compatibility exception	Registry
Playwright	1.63.0	Registry
pnpm	12.4.1	Registry
Wrangler	4.131.1	Registry
Node.js	26.8.2, stable Current release	Releases
Hugo Extended	0.166.0	Release
Go	1.27.1	Releases
OINK	v1.0.0, commit `56583633c4aae4ac7650e9115629bf349728ba90`	Release source

GitHub Actions will use the following verified immutable release commits; no floating tag is used in the workflow:

Action	Release	Commit
actions/checkout	v7.0.1	`3d3c42e5aac5ba805825da76410c181273ba90b1`
actions/setup-node	v7.0.0	`820762786026740c76f36085b0efc47a31fe5020`
actions/upload-artifact	v7.0.1	`043fb46d1a93c77aae656e7c1c64a875d1fc6a0a`
actions/download-artifact	v8.0.1	`3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c`
actions/setup-go	v7.0.0	`b7ad1dad31e06c5925ef5d2fc7ad053ef454303e`
pnpm/action-setup	v6.1.0	`ea17c68df8912ef543352723c149a84f56e3d413`

Plan review

2026-09-13 — foundation_plan_review: PASS, no blockers. Scope: P1 plan and both version tables in EN/ZH, excluding this report, checked against R1. Confirms proportional architecture, concrete checks, deployment safeguards and the specific TypeScript exception. Registry metadata was reviewed as documented, not independently fetched. This pass permits implementation within R1, not commit/publication.

Execution

Delivered the static Astro portfolio and independent Hugo/OINK log site, bilingual Markdown examples, exact tool/dependency pins, tests and one GitHub CI/CD workflow. The log site reads the repository documents through Hugo mounts; no duplicate editable log source or application server is required. OINK is resolved from the recorded release commit to its canonical Go module version, with content fixed by log-site/go.sum.

The release command deploys the checked artifacts, verifies the current main revision inside the production lock and reports partial two-site failures. Deployment stays disabled until external settings are provided. README and the development, content, deployment and workflow guides describe the delivered commands and boundaries. Each change has a Chinese-only local checklist in ignored .local/acceptance/, outside the public Hugo mounts. Public EN/ZH logs retain concise evidence and lasting migration instructions.

Execution review: owner-waived. Only the final acceptance review remains selected. Generated output, tool caches and browser artifacts are ignored; no remote resources or live sites were changed.

Acceptance

Local checks on 2026-09-13, against the uncommitted feat/website-foundation working tree based on ee17e58. Reproduce using the development guide .

Check	Actual result
`pnpm install --frozen-lockfile`	Passed; pnpm lockfile and Go module files unchanged.
`pnpm verify`	Passed: Astro check reported 0 errors/warnings/hints; 19 unit tests; both static builds; 4 output tests; 10 browser tests across desktop/mobile; real content-build fixtures.
Markdown authoring and validation	A new bilingual pair produced pages without component edits; drafts disappeared; missing translations and unsafe slugs caused real builds to fail. Unit tests also cover duplicate routes/keys and inconsistent draft state.
Generated output and browser behavior	9 portfolio pages; all three change articles in both log-site languages. Draft sentinel absent from every portfolio artifact. Local links checked across generated HTML, including unquoted minified attributes. Browser checks cover EN/ZH project identity, mobile overflow, keyboard focus, reduced motion, 404 and actual English/Chinese OINK search results.
`pnpm deploy:dry-run`	Both assets-only Wrangler configurations passed without publishing. `pnpm run deploy` reached the main-push guard and rejected a local invocation without upload. Deployment decision tests cover stale/current revisions, verification errors and upload failures.
Developer documentation	Exact pnpm bootstrap command verified in an isolated prefix; installed executable reports 12.4.1. Persistent EN/ZH guides cover environment setup, server start/stop and checks. The per-change Chinese checklist is local and ignored.
Local/public separation	`git check-ignore` confirms the Chinese checklist is ignored; `git ls-files` contains no local checklist. Its relative links resolve, the public build excludes its content, and all 4 output tests pass after the guide move.
Acceptance and migration contract	Every change requires a Chinese-only local checklist with ordered verification, expected results and migration/recovery or a justified no-migration statement. README, AGENTS and workflow require it even when reviews are waived. Durable evidence and material migration instructions remain in the public bilingual log.
Source inspection	Direct versions and Action release SHAs are fixed; public sources use relative repository references and contain no local workstation paths or credentials. Canonical main remains clean; generated output/caches are excluded.

Migration from ee17e58: the documentation-only baseline has no application database or content store. Record existing tool versions before selecting the pinned tools, install dependencies/Hugo, then run the checks above and verify both languages and existing logs. No existing data or live-site migration is required; 0001/0002 stay at their source paths and are mounted by OINK. If local checks fail, stop the servers, preserve uncommitted work and select the recorded earlier tools if needed; canonical main and the live site remain unchanged. Production activation is separate. Reusable setup/check instructions are in docs/development.md; the temporary checklist is not a required public evidence source.

Pending external acceptance: GitHub Actions execution, required-check/PR enforcement, Cloudflare uploads, routing, DNS and live URLs require authorized remote setup. Local tests do not establish those results. Two-site publication is sequential, not atomic. Final visual design and real personal content are outside this foundation. No commit, push or deployment has been made; owner manual review and the commit checkpoint remain pending.

Acceptance review

2026-09-13 — foundation_acceptance_review: PASS, no remaining material blockers. Scope: the uncommitted foundation based on ee17e58, including EN/ZH documents, Astro/OINK source, pins, tests, CI/CD and final log-table styling, excluding this report. F01–F08 are met within the authorized local foundation scope. The reviewer checked correctness, first-principles simplicity, test/document value and privacy; independently reran 19 unit and 4 output tests and verified the safe deployment-command guard. Full build/browser/dry-run results were assessed from the execution evidence. Remote enforcement/publication and owner manual review remain pending; this pass does not authorize a commit or deployment. The acceptance review also verified the final documentation split: mandatory Chinese-only ignored checklists, maintained EN/ZH guides/public evidence, valid local links, Hugo exclusion, migration/recovery steps and worktree-file lifecycle. No application code or dependency pins changed.