Add build instructions; update README to match spec

README.md

@@ -1,3 +1,36 @@
 # Portfolio
 
-Personal project portfolio.
+Personal portfolio website — interactive professional profile, not a CV pasted onto a webpage.
+
+Built per [INSTRUCTIONS.md](./INSTRUCTIONS.md), which is the full build specification: source-of-truth rules (CV/resume files in this workspace are canonical; no invented facts), section architecture, i18n-first design, animation requirements, Docker deployment, and verification checklist.
+
+## What it presents
+
+- About — who I am, professional summary
+- Experience — work history with dedicated timeline/role UI
+- Projects — browsable project details (purpose, role, tech, outcomes, links)
+- Skills — categorized by actual experience, no invented percentages
+- Education / Certifications
+- Contact + external profiles
+
+## Key properties
+
+- **Section navigation** — persistent nav with addressable URLs (`/en/experience`, `/en/projects`, ...), browser Back/Forward support, animated section transitions that are interruptible and respect `prefers-reduced-motion`
+- **i18n-first** — canonical content layer separate from translations; locale detection (saved choice → browser languages → region hint → default); visible language selector with persistence; `/en/...`, `/vi/...` style URLs with hreflang/canonical metadata
+- **Design** — clean, technical aesthetic; mobile-first, responsive, accessible, keyboard navigable; dark/light mode; simple at first glance, detailed when explored
+- **Performance** — small initial bundle, no heavy animation/UI libraries for effects CSS can do
+
+## Deployment
+
+Docker-based: multi-stage build, non-root runtime user, health check.
+
+```sh
+docker build -t portfolio .
+docker run --rm -p 8080:8080 portfolio
+```
+
+See INSTRUCTIONS.md → "Docker and deployment" for ports, environment variables, and content-editing guides (adding projects, work history, skills, languages).
+
+## Status
+
+Scaffold — repo initialized. Implementation follows the engineering steps in [INSTRUCTIONS.md](./INSTRUCTIONS.md) (inspect workspace sources → canonical content model → i18n/routing/section architecture → animation system → implement → verify).