diff --git a/AGENTS.md b/AGENTS.md index d9bc7db..d148df1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript | Command | Description | |---------|-------------| | `pnpm dev` | Start dev server with HMR | -| `pnpm build` | Type-check (`tsc -b`), build for production (the site-identity plugin fills `%SITE_URL%` / `%SITE_NAME%` in `index.html`), then generate `dist/sitemap.xml` + `dist/robots.txt` | +|`pnpm build`|Type-check (`tsc -b`), build for production (the site-identity plugin fills `%SITE_URL%` / `%SITE_NAME%` in `index.html`), then generate the per-route pages (`dist//index.html` + `dist/404.html`), then `dist/sitemap.xml` + `dist/robots.txt`| | `pnpm build:resume` | Generate resume PDF (default EN) via Playwright | | `pnpm build:resume-all` | Generate bilingual resume PDFs (EN + VI) | | `pnpm lint` | Run Oxlint | @@ -53,6 +53,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript | `/contact` | `ContactPage` | Contact info | | `/philosophy` | `PhilosophyPage` | Engineering philosophy | | `/how-it-works` | `HowItWorksPage` | Intro video: git-backed content, live editing, CI deploy | +| `*` (catch-all) | `NotFoundPage` | In-app 404 for dead links inside the SPA; direct hits on unknown URLs are answered by nginx with a real 404 + the generated `404.html` | ## Theming @@ -77,7 +78,7 @@ Content is split once, at authoring time, into language-neutral **structure docu - `src/data/skills.json` + `skills.ts` loader — skill groups: `{id, skills}`; group titles are text - `src/data/experience.json` + `experience.ts` loader — work history: id / location / logo / optional `variant: 'current' | 'gap'` (timeline decoration: live node / career break); company, duration, titles and responsibilities are text — the VI document carries localized dates ("11/2026 – nay") and company labels, en overrides with the originals, proper nouns identical per language - `src/data/projects.json` + `projects.ts` loader — cards: category / technologies / featured / `sections[].{id, type}`; titles, summaries, role, metrics and section prose are text (role follows the owner's EN title convention; metrics are localized) -- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy..{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 15 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `howItWorks`, `resume`, `edit`, `common`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission +- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy..{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 16 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `howItWorks`, `resume`, `edit`, `common`, `meta`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels, the `notFound` 404 texts, and `meta` — the per-page SEO title/description the route generator writes into each page's head, keyed by PageId for the six static pages and claimed by exactly those six manifests; project pages derive their meta from the content records instead) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission - Content ids and the category values a project uses are **generated**, never hand-maintained (spec: `docs/design/specs/v5/spec-v5-generated-content-ids.md`): `scripts/generate-content-types.ts` reads the four structure documents and writes `src/types/content-ids.ts` (gitignored) under `predev` / `prebuild` / `prepare`; `src/types/index.ts` re-exports those unions type-only and keeps only the code-owned ones (`Language`, `Palette`, `SocialId`, `PageId`, manifest types). A content add or delete touches JSON only — a text entry left behind by a deleted record is a `tsc` error (`TS2741`), never a stale union member — and a category with no label in either language is a validator error naming both `ui/projects.json` files (rule 7) - `src/data/pages/{home,about,experience,projects,project-detail,contact,philosophy,how-it-works,resume}.json` + `pages.ts` loader — per-route manifests: which entity fields the page renders (`fields[]`; `*` = every field the record id owns) and which UI groups it reads; `src/types/index.ts` carries `PageId` / `PageManifestClaim` / `PageManifest`. A manifest describes the whole page, chrome included — the footer renders `profile.name` on every route, so every manifest claims it. The validator enforces: no unknown entity, no unknown UI group, no unresolvable field path, **no orphan text field** (every text leaf in the content documents is claimed by at least one manifest), no missing manifest for a route in `src/data/navigation.ts` plus `/projects/:id` - `src/i18n/index.ts` — load + validate + join ONCE at module load; exports `UI` and `CONTENT` as `Record`; `src/i18n/dict-types.ts` carries the document types; `src/i18n/validate.ts` + `scripts/validate-content.ts` enforce the cross-document rules (orphan or missing keys, HTML markup in text values, the manifest rules above) — a malformed document fails `pnpm build`, CI, and the browser load, never a silent half-render @@ -142,12 +143,13 @@ video/ # standalone Remotion project (spec-v7-intro-video), a pnpm work - `public/resume-logos/` — official company logo SVGs (Lazada, SAP from Wikimedia Commons), embedded in the resume timeline via `ExperienceEntry.logo` - `public/resume-qr/` — owner-supplied QR images (`telegram.jpg`, `zalo.jpg`) embedded in the resume header via `resumeQr` in `src/data/resume.ts`; committed like the other resume assets, so CI renders the QR block too — a missing file prints a warning and that QR is skipped - `public/profile-photo.webp` — profile photo -- `robots.txt` is generated, not committed: `scripts/generate-sitemap.ts` writes `dist/robots.txt` (allow-all + the `Sitemap:` pointer) from the same `SITE_URL` the sitemap uses — no `public/robots.txt` exists anymore +- `robots.txt` is generated, not committed: `scripts/generate-sitemap.ts` writes `dist/robots.txt` (allow-all + the `Sitemap:` pointer) from the same `SITE_URL` the sitemap uses — no `public/robots.txt` exists anymore; the sitemap's `lastmod` per URL is the newest git commit touching the documents that back that page (manifest, claimed entity documents, claimed UI groups), falling back to the build date only when git is unavailable, and a guard refuses any sitemap URL whose generated route file is missing ## Scripts - `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi) - `scripts/generate-content-types.ts` — writes `src/types/content-ids.ts` from the four structure documents (`pnpm generate:ids`, wired as `predev` / `prebuild` / `prepare`): the id unions and the project category values in document order, `never` for an emptied document, a duplicate id refused with the file named +- `scripts/generate-route-pages.ts` — the route-page generator (`pnpm generate:routes`, run by `build` after `vite build`, before the sitemap step; spec-v8 §2): rewrites `dist/index.html`'s head per route with page-specific title/description/canonical/og (static pages from the `meta` UI group, project pages from their content records), adds a manifest-claimed `