feat: add deep-merge utility for profile-based metadata overrides

Replace the full-copy-per-profile approach with a deep-merge function
that recursively merges sparse profile TOML files on top of a shared
root metadata.toml. This lets users vary any field (personal.info,
layout, inject, etc.) per language or target role without duplicating
the entire configuration.

- Add src/utils/merge.typ with recursive deep-merge function
- Export deep-merge from src/lib.typ
- Update template/cv.typ and letter.typ with profile-aware loading
- Restore root metadata.toml and modules_<lang>/ directories
- Remove profile_<lang>/ directories (replaced by profiles/ overrides)
- Add example profile files (en, fr, zh) in template/profiles/
- Update docs: recipes, getting-started, migration guide, API reference

Closes #142

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: yunanwg

docs/web/docs/api-reference.md

@@ -231,6 +231,29 @@ When `ref-full` is `false`, only the entries whose keys appear in
 
 ## Utility Functions
 
+### `deep-merge()`
+
+Recursively merge two dictionaries. Values in `override` take precedence.
+For nested dictionaries, merging is recursive (deep merge). For all other
+value types, the override value replaces the base value entirely.
+
+This is useful for layering a sparse profile configuration on top of a
+complete base `metadata.toml`, so that only the fields that differ need
+to be specified in the profile.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `base` | dictionary | The base dictionary (e.g. root metadata). |
+| `override` | dictionary | The override dictionary whose values win on conflict. |
+
+```typ
+#import "@preview/brilliant-cv:3.0.0": deep-merge
+
+#let base = toml("./metadata.toml")
+#let profile = toml("./profiles/fr.toml")
+#let metadata = deep-merge(base, profile)
+```
+
 ### `h-bar()`
 
 Renders a vertical bar separator (`|`) for use inside skill entries.

docs/web/docs/getting-started.md

@@ -71,7 +71,11 @@ The most important keys to set first:
 typst compile cv.typ
 ```
 
-## Step 7: Go Beyond
+## Step 7: (Optional) Set Up Profiles
+
+If you maintain CVs in multiple languages or for different target roles, you can create **profile overrides** — sparse TOML files that only contain the fields that differ from your root `metadata.toml`. See [Recipes → Profile-Based Overrides](recipes.md#profile-based-overrides) for details.
+
+## Step 8: Go Beyond
 
 It is recommended to:
 

docs/web/docs/migration.md

@@ -2,19 +2,15 @@
 
 ## Migration from v3
 
-v4 replaces the language-based switching system with a **profile-based** architecture. Each profile is a self-contained folder with its own `metadata.toml` and module files, enabling full customization per variant — not just language-specific quotes, but also different personal info, layout, and keywords per target role or industry.
+v4 adds a **`deep-merge` utility function** to the package, enabling profile-based overrides. This lets you vary any metadata field per language or target role — not just `header_quote` and footers, but also `[personal.info]`, `[layout]`, `[inject]`, and anything else ([#142](https://github.com/yunanwg/brilliant-CV/issues/142)).
 
-### Why this change?
+### What changed?
 
-In v3, all CV variants share a single `metadata.toml`. The `[lang.<code>]` sections only allow varying `header_quote`, `cv_footer`, and `letter_footer` per language. Fields like `[personal.info]`, `[layout]`, and `[inject]` are global and cannot differ between languages or target roles ([#142](https://github.com/yunanwg/brilliant-CV/issues/142)).
+The package now exports `deep-merge`, a recursive dictionary merge function. Your root `metadata.toml` stays as the single source of truth; optional profile files contain only the fields that differ.
 
-The new profile system makes each variant fully independent: a `profile_en/` folder for your English CV, a `profile_fr/` for French, a `profile_swe/` tailored for software engineering roles — each with its own metadata, personal info, and content modules.
+### Zero-effort upgrade
 
-### Upgrade paths
-
-#### Option A: Zero-effort upgrade (keep v3 structure)
-
-The v4 package is **fully backward compatible** with the v3 metadata format. If you don't need per-profile customization, just update the version number:
+v4 is **fully backward compatible**. If you don't need per-profile customization, just update the version number:
 
 ```typ
 // Before
@@ -24,97 +20,62 @@ The v4 package is **fully backward compatible** with the v3 metadata format. If
 #import "@preview/brilliant-cv:4.0.0": cv
 ```
 
-Your existing `metadata.toml` with `[lang.<code>]` sections, `modules_<lang>/` folders, and `--input language=xx` CLI pattern will continue to work as before.
-
-#### Option B: Migrate to profile-based structure
+Your existing `metadata.toml`, `modules_<lang>/` folders, `[lang.<code>]` sections, and `--input language=xx` all continue to work unchanged.
 
-Follow these steps to adopt the new architecture:
+### Adopting profile overrides (optional)
 
-**1. Rename module folders**
-
-```
-modules_en/  →  profile_en/
-modules_fr/  →  profile_fr/
-```
+To vary fields like `personal.info.location` per language:
 
-**2. Create per-profile `metadata.toml`**
-
-Copy your root `metadata.toml` into each profile folder and make these changes:
+**1. Create sparse profile files** in a `profiles/` directory:
 
 ```toml
-# Before (v3 root metadata.toml)
-language = "en"
-
-[lang.en]
-    header_quote = "Experienced Data Analyst..."
-    cv_footer = "Curriculum vitae"
-    letter_footer = "Cover letter"
-
-[lang.non_latin]
-    name = "王道尔"
-    font = "Heiti SC"
-
-# After (profile_en/metadata.toml) — flat, no [lang] nesting
-language = "en"
-header_quote = "Experienced Data Analyst..."
-cv_footer = "Curriculum vitae"
-letter_footer = "Cover letter"
-```
+# profiles/fr.toml — only the fields that differ
+language = "fr"
 
-For non-Latin profiles (zh, ja, ko, ru), move the non-Latin settings to top-level:
+[personal.info]
+  location = "Paris, France"
 
-```toml
-# profile_zh/metadata.toml
-language = "zh"
-header_quote = "具有丰富经验的数据分析师，随时可入职"
-cv_footer = "简历"
-letter_footer = "申请信"
-non_latin_name = "王道尔"
-non_latin_font = "Heiti SC"
+  [personal.info.custom-1]
+    awesomeIcon = "car"
+    text = "Permis B"
 ```
 
-Remove the `[lang.*]` sections entirely from each profile's `metadata.toml`. You can now customize `[personal]`, `[layout]`, `[inject]`, and all other sections independently per profile.
-
-**3. Update `cv.typ`**
+**2. Update your `cv.typ` import and preamble:**
 
 ```typ
 // Before (v3)
+#import "@preview/brilliant-cv:3.2.0": cv
+
+// After (v4) — add deep-merge to the import
+#import "@preview/brilliant-cv:4.0.0": cv, deep-merge
 #let metadata = toml("./metadata.toml")
+
+// Profile override (new)
+#let cv-profile = sys.inputs.at("profile", default: metadata.at("profile", default: none))
+#let metadata = if cv-profile != none {
+  deep-merge(metadata, toml("./profiles/" + cv-profile + ".toml"))
+} else {
+  metadata
+}
+
+// --input language=xx still works as before
 #let cv-language = sys.inputs.at("language", default: none)
 #let metadata = if cv-language != none {
   metadata + (language: cv-language)
 } else {
   metadata
 }
-#let import-modules(modules, lang: metadata.language) = {
-  for module in modules {
-    include { "modules_" + lang + "/" + module + ".typ" }
-  }
-}
-
-// After (v4)
-#let profile = sys.inputs.at("profile", default: "en")
-#let metadata = toml("profile_" + profile + "/metadata.toml")
-#let import-modules(modules) = {
-  for module in modules {
-    include { "profile_" + profile + "/" + module + ".typ" }
-  }
-}
 ```
 
-**4. Update `letter.typ`** — same pattern as `cv.typ`.
+**3. Update `letter.typ`** — same preamble pattern.
 
-**5. Update CLI commands**
+**4. Build with a profile:**
 
 ```bash
-# Before
-typst compile cv.typ --input language=fr
-
-# After
 typst compile cv.typ --input profile=fr
 ```
 
-**6. Clean up** — delete the root `metadata.toml` (each profile folder now has its own).
+See [Recipes → Profile-Based Overrides](recipes.md#profile-based-overrides) for full details and examples.
 
 ---
 

docs/web/docs/recipes.md

@@ -14,6 +14,65 @@ typst compile cv.typ --input language=fr
 
 For Chinese, Japanese, Korean, or Russian, also configure `[lang.non_latin]` in `metadata.toml` with `name` and `font`.
 
+## Profile-Based Overrides
+
+If you need different `personal.info` fields per language or target role — for example, "Permis B" instead of "Driver License", or "Paris" instead of "San Francisco" — you can use **profile overrides**.
+
+A profile is a sparse TOML file that gets [deep-merged](api-reference.md) on top of your root `metadata.toml`. Only the fields that differ need to be specified.
+
+### Setup
+
+**1. Create a `profiles/` directory** with one TOML file per variant:
+
+```
+profiles/
+  en.toml   ← minimal (language is already "en" in root)
+  fr.toml   ← overrides language + French-specific fields
+```
+
+**2. Write sparse overrides.** For example, `profiles/fr.toml`:
+
+```toml
+language = "fr"
+
+[personal.info]
+  location = "Paris, France"
+
+  [personal.info.custom-1]
+    awesomeIcon = "car"
+    text = "Permis B"
+```
+
+Everything not specified (layout, fonts, email, GitHub, etc.) is inherited from root `metadata.toml`.
+
+**3. Build with a profile:**
+
+```bash
+typst compile cv.typ --input profile=fr
+```
+
+Or set a default in `metadata.toml`:
+
+```toml
+profile = "en"
+```
+
+### How deep-merge works
+
+The `deep-merge` function recursively combines two dictionaries:
+
+- **No conflict** (key only in one dict) → value is kept as-is
+- **Both have the key, both are dicts** → merge recursively (go deeper)
+- **Both have the key, not both dicts** → profile value wins
+
+This means `profiles/fr.toml` only overrides `personal.info.location` and `personal.info.custom-1` — all other `personal.info` fields (email, phone, github, etc.) are preserved from root.
+
+### Tips
+
+- **Profile ≠ language.** You can have `profiles/us.toml` and `profiles/uk.toml` both with `language = "en"` but different locations or phone numbers.
+- **`--input language=xx` still works** as a final override on top of a profile, for backward compatibility.
+- **Profiles are optional.** If you don't use them, everything works exactly as before.
+
 ## Skills with Inline Separators
 
 Use `#h-bar()` to separate skill items within `cv-skill`:

docs/web/generate-api-reference.py

@@ -33,6 +33,29 @@
 
 ## Utility Functions
 
+### `deep-merge()`
+
+Recursively merge two dictionaries. Values in `override` take precedence.
+For nested dictionaries, merging is recursive (deep merge). For all other
+value types, the override value replaces the base value entirely.
+
+This is useful for layering a sparse profile configuration on top of a
+complete base `metadata.toml`, so that only the fields that differ need
+to be specified in the profile.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `base` | dictionary | The base dictionary (e.g. root metadata). |
+| `override` | dictionary | The override dictionary whose values win on conflict. |
+
+```typ
+#import "@preview/brilliant-cv:3.0.0": deep-merge
+
+#let base = toml("./metadata.toml")
+#let profile = toml("./profiles/fr.toml")
+#let metadata = deep-merge(base, profile)
+```
+
 ### `h-bar()`
 
 Renders a vertical bar separator (`|`) for use inside skill entries.

src/lib.typ

@@ -7,6 +7,7 @@
 #import "./letter.typ": *
 #import "./utils/lang.typ": *
 #import "./utils/styles.typ": *
+#import "./utils/merge.typ": deep-merge
 
 /* Layout */
 

src/utils/merge.typ

@@ -0,0 +1,22 @@
+/// Recursively merge two dictionaries. Values in `override` take precedence.
+/// For nested dictionaries, merging is recursive (deep merge). For all other
+/// value types, the override value replaces the base value entirely.
+///
+/// This is useful for layering a sparse profile configuration on top of a
+/// complete base `metadata.toml`, so that only the fields that differ need
+/// to be specified in the profile.
+///
+/// - base (dictionary): The base dictionary (e.g. root metadata).
+/// - override (dictionary): The override dictionary whose values win on conflict.
+/// -> dictionary
+#let deep-merge(base, override) = {
+  let result = base
+  for (key, value) in override {
+    if key in result and type(result.at(key)) == dictionary and type(value) == dictionary {
+      result.insert(key, deep-merge(result.at(key), value))
+    } else {
+      result.insert(key, value)
+    }
+  }
+  result
+}

template/cv.typ

@@ -1,18 +1,28 @@
 // Imports
-#import "@preview/brilliant-cv:3.2.0": cv
+#import "@preview/brilliant-cv:3.2.0": cv, deep-merge
+#let metadata = toml("./metadata.toml")
 
-// Select which profile to build. Each profile lives in its own folder
-// (e.g. profile_en/, profile_fr/, profile_solution_engineer/) with its
-// own metadata.toml and module files.
-//
+// Profile override: deep-merge a sparse profile TOML on top of root config.
 // Override via CLI: typst compile cv.typ --input profile=fr
-#let profile = sys.inputs.at("profile", default: "en")
-#let metadata = toml("profile_" + profile + "/metadata.toml")
+#let cv-profile = sys.inputs.at("profile", default: metadata.at("profile", default: none))
+#let metadata = if cv-profile != none {
+  deep-merge(metadata, toml("./profiles/" + cv-profile + ".toml"))
+} else {
+  metadata
+}
+
+// Backward compat: --input language=xx still works as a final override
+#let cv-language = sys.inputs.at("language", default: none)
+#let metadata = if cv-language != none {
+  metadata + (language: cv-language)
+} else {
+  metadata
+}
 
-#let import-modules(modules) = {
+#let import-modules(modules, lang: metadata.language) = {
   for module in modules {
     include {
-      "profile_" + profile + "/" + module + ".typ"
+      "modules_" + lang + "/" + module + ".typ"
     }
   }
 }
@@ -27,7 +37,6 @@
   // ),
 )
 
-// Add, remove, or reorder modules to customize your CV content
 #import-modules((
   "education",
   "professional",

template/letter.typ

@@ -1,10 +1,23 @@
 // Imports
-#import "@preview/brilliant-cv:3.2.0": letter
+#import "@preview/brilliant-cv:3.2.0": letter, deep-merge
+#let metadata = toml("./metadata.toml")
 
-// Select which profile to build (must match a profile_<name>/ folder)
+// Profile override: deep-merge a sparse profile TOML on top of root config.
 // Override via CLI: typst compile letter.typ --input profile=fr
-#let profile = sys.inputs.at("profile", default: "en")
-#let metadata = toml("profile_" + profile + "/metadata.toml")
+#let letter-profile = sys.inputs.at("profile", default: metadata.at("profile", default: none))
+#let metadata = if letter-profile != none {
+  deep-merge(metadata, toml("./profiles/" + letter-profile + ".toml"))
+} else {
+  metadata
+}
+
+// Backward compat: --input language=xx still works as a final override
+#let letter-language = sys.inputs.at("language", default: none)
+#let metadata = if letter-language != none {
+  metadata + (language: letter-language)
+} else {
+  metadata
+}
 
 
 #show: letter.with(