diff --git a/AGENTS.md b/AGENTS.md
index 4c5fe75..4b5daf4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,6 +88,19 @@ src/
4. **Theme from system:** When stored theme is `'system'`, `cycleTheme` must skip to opposite theme on first click (not go to `'dark'` which resolves to same visual)
5. **Footer/Nav links:** Must use ``, not `` for client-side navigation
+## Design Specs
+
+All specification documents are in `docs/design/`:
+
+| File | Purpose |
+|------|---------|
+| `spec.md` | Main PRD — product vision, positioning, narrative, IA, acceptance criteria |
+| `spec_v1.md` | v1 completion record — features implemented, known limitations, files summary |
+| `spec-v2.md` | v2 features — Resume, Blog, SEO, Analytics, Testing, CI/CD |
+| `spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) |
+
+Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
+
## Code Style & Linting
- TypeScript: `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`
diff --git a/spec-ui-about.md b/docs/design/spec-ui-about.md
similarity index 100%
rename from spec-ui-about.md
rename to docs/design/spec-ui-about.md
diff --git a/spec-ui-blog.md b/docs/design/spec-ui-blog.md
similarity index 100%
rename from spec-ui-blog.md
rename to docs/design/spec-ui-blog.md
diff --git a/spec-ui-components.md b/docs/design/spec-ui-components.md
similarity index 100%
rename from spec-ui-components.md
rename to docs/design/spec-ui-components.md
diff --git a/spec-ui-contact.md b/docs/design/spec-ui-contact.md
similarity index 100%
rename from spec-ui-contact.md
rename to docs/design/spec-ui-contact.md
diff --git a/spec-ui-engineering.md b/docs/design/spec-ui-engineering.md
similarity index 100%
rename from spec-ui-engineering.md
rename to docs/design/spec-ui-engineering.md
diff --git a/spec-ui-experience.md b/docs/design/spec-ui-experience.md
similarity index 100%
rename from spec-ui-experience.md
rename to docs/design/spec-ui-experience.md
diff --git a/spec-ui-expertise.md b/docs/design/spec-ui-expertise.md
similarity index 100%
rename from spec-ui-expertise.md
rename to docs/design/spec-ui-expertise.md
diff --git a/spec-ui-footer.md b/docs/design/spec-ui-footer.md
similarity index 100%
rename from spec-ui-footer.md
rename to docs/design/spec-ui-footer.md
diff --git a/spec-ui-hero.md b/docs/design/spec-ui-hero.md
similarity index 100%
rename from spec-ui-hero.md
rename to docs/design/spec-ui-hero.md
diff --git a/spec-ui-layout.md b/docs/design/spec-ui-layout.md
similarity index 100%
rename from spec-ui-layout.md
rename to docs/design/spec-ui-layout.md
diff --git a/spec-ui-navigation.md b/docs/design/spec-ui-navigation.md
similarity index 100%
rename from spec-ui-navigation.md
rename to docs/design/spec-ui-navigation.md
diff --git a/spec-ui-project-detail.md b/docs/design/spec-ui-project-detail.md
similarity index 100%
rename from spec-ui-project-detail.md
rename to docs/design/spec-ui-project-detail.md
diff --git a/spec-ui-projects-list.md b/docs/design/spec-ui-projects-list.md
similarity index 100%
rename from spec-ui-projects-list.md
rename to docs/design/spec-ui-projects-list.md
diff --git a/spec-ui-projects.md b/docs/design/spec-ui-projects.md
similarity index 100%
rename from spec-ui-projects.md
rename to docs/design/spec-ui-projects.md
diff --git a/docs/design/spec-v2.md b/docs/design/spec-v2.md
new file mode 100644
index 0000000..09ddf08
--- /dev/null
+++ b/docs/design/spec-v2.md
@@ -0,0 +1,441 @@
+# Specification — v2 Features
+
+> **Document:** `spec-v2.md`
+> **Version:** 0.1.0
+> **Status:** Draft — awaiting review
+> **Branch:** `dev_v2`
+> **Parent branch:** `dev` (v0.0.1)
+
+---
+
+## Overview
+
+Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào:
+
+1. **Resume download** (P1)
+2. **Blog system** — MDX-based articles (P1)
+3. **SEO** — metadata, Open Graph, sitemap (P1)
+4. **Analytics** — privacy-friendly page view tracking (P2)
+5. **Testing** — Vitest + Testing Library (P5)
+6. **CI/CD pipeline** (P5)
+
+---
+
+## 1. Resume Download
+
+### Requirement
+
+- Nút "Download Resume" trong nav hoặc Contact page
+- Link đến file PDF (placeholder ban đầu)
+- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon"
+- PDF sẽ upload vào `public/resume.pdf`
+
+### Implementation
+
+```tsx
+// Navigation.tsx
+{resumeAvailable && (
+ Resume
+)}
+
+// OR ContactPage.tsx
+Download Resume
+```
+
+### Data
+
+- `public/resume.pdf` — PDF file (user tự upload)
+- Không cần data module
+
+### Acceptance
+
+- [ ] Nút Resume hiển thị trong nav
+- [ ] Click → download PDF
+- [ ] Khi chưa có PDF → nút ẩn hoặc disabled
+- [ ] Responsive trên mobile
+
+---
+
+## 2. Blog System
+
+### Requirement
+
+Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
+
+### Architecture
+
+```
+src/
+ content/
+ blog/
+ post-1.mdx
+ post-2.mdx
+ components/
+ blog/
+ BlogListPage.tsx
+ BlogPostPage.tsx
+ ArticleCard.tsx
+ CodeBlock.tsx
+```
+
+### Features
+
+#### 2.1. Frontmatter
+
+Mỗi article có frontmatter:
+
+```yaml
+---
+title: "Building High-Performance Event Simulation with Go"
+date: "2024-06-15"
+tags: ["engineering", "golang", "simulation"]
+summary: "Discrete event simulation for logistics facilities"
+---
+```
+
+#### 2.2. Blog List Page (`/blog`)
+
+- Hiển thị danh sách articles
+- Sort theo date (newest first)
+- Filter theo tags (pill buttons)
+- Mỗi article card: title, date, tags, summary
+
+#### 2.3. Article Page (`/blog/:slug`)
+
+- Render MDX content
+- Code blocks với syntax highlighting
+- TOC (table of contents) sidebar (desktop)
+- Reading time estimate
+- Breadcrumb navigation
+
+#### 2.4. Code Highlighting
+
+- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
+- Không dùng library nặng như `react-syntax-highlighter`
+- Theme: dark/light compatible với CSS variables
+
+#### 2.5. MDX Processing
+
+- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
+- Build-time compilation (không runtime)
+- Frontmatter extracted tại build time
+
+### Vite Config Changes
+
+```ts
+// vite.config.ts
+import mdx from '@mdx-js/rollup'
+
+export default defineConfig({
+ plugins: [
+ react(),
+ mdx({
+ providerImportSource: '@mdx-js/react',
+ }),
+ ],
+})
+```
+
+### Acceptance
+
+- [ ] `/blog` hiển thị danh sách articles
+- [ ] Article card có title, date, tags, summary
+- [ ] Click article → navigate đến `/blog/:slug`
+- [ ] MDX content render đúng
+- [ ] Code blocks có syntax highlighting
+- [ ] Tags filter hoạt động
+- [ ] TOC sidebar (desktop only)
+- [ ] Reading time hiển thị
+- [ ] Responsive
+- [ ] Không crash khi missing article
+
+---
+
+## 3. SEO
+
+### Requirement
+
+Mỗi page có metadata riêng cho SEO và social sharing.
+
+### Implementation
+
+#### 3.1. Dynamic Metadata
+
+Dùng `react-helmet-async` (hoặc `@remix-run/react` helmet nếu cần SSR sau này).
+
+```tsx
+import { Helmet } from 'react-helmet-async'
+
+// HomePage.tsx
+
+ {profile.name} — Senior Software Engineer
+
+
+
+```
+
+#### 3.2. Open Graph
+
+Mỗi page có OG tags:
+
+```html
+
+
+
+
+
+```
+
+#### 3.3. Sitemap
+
+- Generate `sitemap.xml` tại build time
+- Dùng `vite-plugin-sitemap` hoặc tự viết script
+- Include tất cả public pages
+
+#### 3.4. Robots.txt
+
+- `public/robots.txt`
+- Allow all (trừ `/admin` nếu có sau này)
+
+#### 3.5. Structured Data (JSON-LD)
+
+- `Person` schema cho homepage
+- `Article` schema cho blog posts
+- `BreadcrumbList` cho nested pages
+
+### Acceptance
+
+- [ ] Mỗi page có `
` và `` riêng
+- [ ] OG tags đúng trên mỗi page
+- [ ] `sitemap.xml` generated tại build
+- [ ] `robots.txt` có trong `public/`
+- [ ] JSON-LD structured data
+- [ ] Canonical URL đúng
+
+---
+
+## 4. Analytics
+
+### Requirement
+
+Privacy-friendly analytics — không dùng Google Analytics.
+
+### Options
+
+**Option A: Plausible Analytics** (recommended)
+- Lightweight, privacy-first
+- No cookie banner needed
+- Simple script integration
+
+**Option B: Umami**
+- Self-hosted option
+- Open source
+- Similar to Plausible
+
+**Option C: Custom minimal tracking**
+- Track page views only
+- Store in localStorage
+- Batch send to endpoint (optional)
+
+### Implementation (Plausible)
+
+```tsx
+// main.tsx
+
+```
+
+Hoặc dùng `react-use-plausible`:
+
+```tsx
+import { usePlausible } from 'react-use-plausible'
+
+const plausible = usePlausible()
+// Auto pageview tracking
+```
+
+### Acceptance
+
+- [ ] Page view tracking hoạt động
+- [ ] Không cookie banner
+- [ ] Không ảnh hưởng performance
+- [ ] Configurable via env var (ENABLE_ANALYTICS)
+
+---
+
+## 5. Testing
+
+### Requirement
+
+Unit tests cho components và hooks. E2E tests cho critical paths.
+
+### Stack
+
+- **Vitest** — unit/integration tests
+- **@testing-library/react** — component tests
+- **@testing-library/jest-dom** — assertions
+- **Playwright** — E2E tests
+
+### Test Structure
+
+```
+src/
+ __tests__/
+ hooks/
+ useTheme.test.tsx
+ components/
+ Navigation.test.tsx
+ Footer.test.tsx
+ Badge.test.tsx
+ pages/
+ HomePage.test.tsx
+ e2e/
+ navigation.spec.ts
+ theme.spec.ts
+ responsive.spec.ts
+```
+
+### Critical Tests
+
+#### useTheme
+
+```tsx
+test('cycles through themes correctly', () => {
+ const { result } = renderHook(() => useTheme())
+ act(() => { result.current.cycleTheme() })
+ expect(result.current.theme).toBe('light') // or 'dark'
+})
+
+test('persists theme to localStorage', () => {
+ renderHook(() => useTheme())
+ expect(localStorage.getItem('portfolio-theme')).toBe('dark')
+})
+```
+
+#### Navigation
+
+```tsx
+test('renders all nav items', () => {
+ render()
+ navItems.forEach(item => {
+ expect(screen.getByText(item.label)).toBeInTheDocument()
+ })
+})
+
+test('NavLink highlights active route', () => {
+ render( )
+ expect(screen.getByText('About')).toHaveClass('active')
+})
+```
+
+#### HomePage
+
+```tsx
+test('renders hero section', () => {
+ render()
+ expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
+})
+```
+
+### Acceptance
+
+- [ ] useTheme tests pass
+- [ ] Navigation tests pass
+- [ ] HomePage tests pass
+- [ ] E2E: navigation works
+- [ ] E2E: theme toggle works
+- [ ] E2E: responsive layout correct
+- [ ] Test coverage > 70%
+
+---
+
+## 6. CI/CD Pipeline
+
+### Requirement
+
+GitHub Actions pipeline:
+
+1. **Lint** — oxlint
+2. **Type check** — tsc -b
+3. **Test** — vitest
+4. **Build** — vite build
+5. **Deploy** — to Vercel (on main branch push)
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+ push:
+ branches: [dev, main]
+ pull_request:
+ branches: [dev]
+
+jobs:
+ ci:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: pnpm
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm lint
+ - run: pnpm build
+ - run: pnpm test
+```
+
+### Vercel Integration
+
+- Connect GitHub repo
+- Auto deploy on `dev` → preview
+- Auto deploy on `main` → production
+- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
+
+### Acceptance
+
+- [ ] CI pass trên push vào dev
+- [ ] Lint pass
+- [ ] Build pass
+- [ ] Tests pass
+- [ ] Preview deploy trên Vercel
+- [ ] Production deploy khi merge vào main
+
+---
+
+## Implementation Order
+
+Ưu tiên thực hiện:
+
+1. **Resume download** (5 phút, trivial)
+2. **SEO** (metadata, OG, sitemap) — cần làm trước khi deploy
+3. **Blog system** (MDX + articles) — P1, substantial work
+4. **Analytics** (Plausible) — quick win
+5. **Testing** (Vitest + E2E) — P5, important but can iterate
+6. **CI/CD** (GitHub Actions) — P5, automate after features done
+
+---
+
+## Out of Scope (v2)
+
+- CMS integration (Phase 5+)
+- Multi-language / i18n (Phase 5+)
+- Interactive diagrams / simulations (Phase 5+)
+- Search functionality (Phase 5+)
+- Contact form with backend (Phase 5+)
+- Resume PDF generation (user uploads manually)
+
+---
+
+## Approval
+
+- [ ] All requirements reviewed and confirmed
+- [ ] Implementation order agreed
+- [ ] Ready to start coding
diff --git a/spec.md b/docs/design/spec.md
similarity index 100%
rename from spec.md
rename to docs/design/spec.md
diff --git a/docs/design/spec_v1.md b/docs/design/spec_v1.md
new file mode 100644
index 0000000..353e13b
--- /dev/null
+++ b/docs/design/spec_v1.md
@@ -0,0 +1,174 @@
+# Specification — v1 (Foundation + Core Portfolio)
+
+> **Document:** `spec_v1.md`
+> **Version:** 1.0.0
+> **Status:** Completed
+> **Branch:** `dev` (merged from `dev_v1`)
+> **Tag:** `v0.0.1`
+> **Commit:** `7e42bd8` (feat) + `59951a7` (docs)
+
+---
+
+## Overview
+
+v1 implements **Phase 1 (Foundation)** and **Phase 2 (Core Portfolio)** from `spec.md`. All pages, components, theming, and responsive layout are complete.
+
+---
+
+## Completed Features
+
+### 1. Foundation
+
+| Feature | Status | Details |
+|---------|--------|---------|
+| Vite 8 + React 19 + TypeScript 6 | Done | Bundler mode, strict linting |
+| Oxlint 1 | Done | `react/rules-of-hooks` error, `react/only-export-components` warn |
+| React Router v6 | Done | Pin `6.30.6`, 7 routes defined |
+| CSS Variables + Theming | Done | `data-theme` attribute, dark/light/system |
+| Responsive Design | Done | Mobile menu, fluid containers, touch-friendly |
+
+### 2. Routing & Pages
+
+| Route | Page | Component | Status |
+|-------|------|-----------|--------|
+| `/` | Home | `HomePage` | Done |
+| `/about` | About | `AboutPage` | Done |
+| `/experience` | Experience | `ExperiencePage` | Done |
+| `/projects` | Projects List | `ProjectsListPage` | Done |
+| `/projects/:id` | Project Detail | `ProjectDetailPage` | Done |
+| `/engineering` | Engineering | `EngineeringPage` | Done (placeholder content) |
+| `/contact` | Contact | `ContactPage` | Done |
+
+### 3. Layout Components
+
+| Component | File | Status |
+|-----------|------|--------|
+| `Layout` | `src/components/layout/Layout.tsx` | Done — wraps Navigation + main + Footer |
+| `Navigation` | `src/components/layout/Navigation.tsx` | Done — desktop menu, mobile drawer, theme toggle |
+| `Footer` | `src/components/layout/Footer.tsx` | Done — copyright, nav links, social links |
+
+### 4. Page Sections (HomePage)
+
+| Section | Component | Status |
+|---------|-----------|--------|
+| Hero | `src/components/sections/Hero.tsx` | Done — name, title, tagline, CTA, social links |
+| About | `src/components/sections/About.tsx` | Done — bio, engineering philosophy, current interests |
+| Expertise | `src/components/sections/Expertise.tsx` | Done — skill groups grid |
+| Experience | `src/components/sections/Experience.tsx` | Done — timeline with responsibilities |
+| Projects | `src/components/sections/Projects.tsx` | Done — featured projects grid |
+| Contact | `src/components/sections/Contact.tsx` | Done — email, GitHub, LinkedIn links |
+
+### 5. UI Components
+
+| Component | File | Props/Features | Status |
+|-----------|------|----------------|--------|
+| `Button` | `src/components/ui/Button.tsx` | `variant`, `size`, `disabled` | Done |
+| `Badge` | `src/components/ui/Badge.tsx` | `variant: accent | outline | muted` | Done |
+| `Tag` | `src/components/ui/Tag.tsx` | `accent` | Done |
+| `Card` | `src/components/ui/Card.tsx` | `as`, children | Done |
+| `SectionHeading` | `src/components/ui/SectionHeading.tsx` | `title`, `subtitle` | Done |
+| `SocialLinks` | `src/components/ui/SocialLinks.tsx` | `links`, `variant` | Done |
+
+### 6. Theming
+
+| Feature | Status | Details |
+|---------|--------|---------|
+| `ThemeProvider` | Done | Context provider, `data-theme` on `` |
+| `useTheme()` hook | Done | Returns `{ theme, resolvedTheme, setTheme, cycleTheme }` |
+| Theme cycle | Done | `dark` ↔ `light` ↔ `system` (system skips to opposite) |
+| localStorage persistence | Done | Key: `portfolio-theme` |
+| System preference detection | Done | `prefers-color-scheme: dark` |
+| CSS variables for both themes | Done | `src/index.css` root + `[data-theme="dark"]` |
+
+### 7. Data Layer
+
+| Module | File | Content | Status |
+|--------|------|---------|--------|
+| Profile | `src/data/profile.ts` | Name, title, tagline, bio, links, interests, philosophy | Done |
+| Skills | `src/data/skills.ts` | 6 skill groups × 5-6 skills each | Done |
+| Experience | `src/data/experience.ts` | 1 entry with 3 featured achievements | Done |
+| Projects | `src/data/projects.ts` | 4 projects with sections, metrics, tech stacks | Done |
+
+### 8. Types
+
+| Interface | File | Fields | Status |
+|-----------|------|--------|--------|
+| `Profile` | `src/types/index.ts` | name, title, tagline, bio, email, links, interests, philosophy | Done |
+| `SkillGroup` | `src/types/index.ts` | title, skills[] | Done |
+| `ExperienceEntry` | `src/types/index.ts` | id, title, company, duration, location, responsibilities, achievements | Done |
+| `FeaturedAchievement` | `src/types/index.ts` | id, title, context, technicalWork, impact, metrics, technologies, featured | Done |
+| `Project` | `src/types/index.ts` | id, title, summary, category, role, technologies, metrics, featured, urls | Done |
+| `ProjectDetail` | `src/types/index.ts` | extends Project + sections[] | Done |
+| `ProjectSection` | `src/types/index.ts` | id, number, title, content, type | Done |
+| `PhilosophyPoint` | `src/types/index.ts` | title, description, keywords[] | Done |
+| `ProjectCategory` | `src/types/index.ts` | 6 union types | Done |
+
+---
+
+## Architecture
+
+```
+App.tsx
+ └── ThemeProvider
+ └── BrowserRouter
+ └── Layout
+ ├── Navigation (top bar + mobile drawer)
+ ├──
+ │ ├── HomePage (Hero + About + Expertise + Experience + Projects + Contact)
+ │ ├── AboutPage
+ │ ├── ExperiencePage
+ │ ├── ProjectsListPage
+ │ ├── ProjectDetailPage
+ │ ├── EngineeringPage
+ │ └── ContactPage
+ └── Footer
+```
+
+**Data flow:** All content comes from `src/data/*.ts` modules. Components are presentational — no hardcoded text except labels/CTAs.
+
+**CSS:** Global variables in `src/index.css`, component styles in `src/App.css`. No CSS library.
+
+---
+
+## Known Limitations
+
+| # | Limitation | Impact | v2 Plan |
+|---|------------|--------|---------|
+| 1 | No Blog system | Cannot publish articles | Phase 4: MDX-based blog |
+| 2 | No SEO metadata | No ``, ``, OG tags per page | Phase 5: react-helmet-async |
+| 3 | No Analytics | No page view tracking | Phase 5: Plausible |
+| 4 | No Testing | No unit/E2E tests | Phase 5: Vitest + Playwright |
+| 5 | No CI/CD | Manual builds only | Phase 5: GitHub Actions |
+| 6 | No Resume download | No PDF resume | v2: Add link/button |
+| 7 | Engineering page placeholder | "Coming soon" text | v2: Populate with real content |
+| 8 | Projects use `` not `` | Client-side nav broken on projects page | v2: Fix to `` |
+| 9 | No i18n | Vietnamese-only | Future: English support |
+| 10 | No CMS | Content in TS files | Future: headless CMS or MDX |
+
+---
+
+## Files Summary
+
+| Category | Count | Path |
+|----------|-------|------|
+| Pages | 7 | `src/pages/*.tsx` |
+| Layout components | 3 | `src/components/layout/*.tsx` |
+| Section components | 6 | `src/components/sections/*.tsx` |
+| UI components | 6 | `src/components/ui/*.tsx` |
+| Data modules | 4 | `src/data/*.ts` |
+| Hooks | 1 | `src/hooks/useTheme.tsx` |
+| Types | 1 | `src/types/index.ts` |
+| CSS | 2 | `src/index.css`, `src/App.css` |
+| **Total source files** | **30** | |
+
+---
+
+## Approval
+
+- [x] All Phase 1 + Phase 2 requirements implemented
+- [x] TypeScript compiles without errors
+- [x] Oxlint passes
+- [x] Build succeeds
+- [x] Responsive on mobile/desktop
+- [x] Tagged `v0.0.1` on branch `dev`
+- [x] AGENTS.md updated with project context