From 79e1f6cc84f95aba834f4dbb9206781c52379a70 Mon Sep 17 00:00:00 2001
From: Huyen Nguyen <25715018+huyenltnguyen@users.noreply.github.com>
Date: Fri, 6 Mar 2026 03:48:19 +0700
Subject: [PATCH 1/4] docs: add language curricula guide

---
 .../how-to-work-on-language-curricula.mdx     | 105 ++++++++++++++++++
 src/sidebar.ts                                |   1 +
 2 files changed, 106 insertions(+)
 create mode 100644 src/content/docs/how-to-work-on-language-curricula.mdx

diff --git a/src/content/docs/how-to-work-on-language-curricula.mdx b/src/content/docs/how-to-work-on-language-curricula.mdx
new file mode 100644
index 00000000..ae55bb6d
--- /dev/null
+++ b/src/content/docs/how-to-work-on-language-curricula.mdx
@@ -0,0 +1,105 @@
+---
+title: How to Work on Language Curricula
+sidebar:
+  label: Work on Language Curricula
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
+
+## Using Challenge Helper Scripts
+
+All commands must be run from the `tools/challenge-helper-scripts` directory. To navigate to this directory, run:
+
+```bash
+cd tools/challenge-helper-scripts
+```
+
+## Creating a New Block
+
+To create a new block, run:
+
+```bash
+pnpm run create-language-block
+```
+
+The script walks you through a series of prompts:
+
+| Prompt            | What to provide                                              |
+| ----------------- | ------------------------------------------------------------ |
+| Super block       | The super block this block belongs to (e.g., A2 English)     |
+| Block label       | The type of block: `practice`, `learn`, `quiz`, etc.         |
+| Block dashed name | A unique kebab-case identifier for the block                 |
+| Block title       | A human-readable title (defaults to the dashed name)         |
+| Help category     | The support category for this block's forum posts            |
+| Block layout      | The visual layout used to display challenges                 |
+| Chapter           | The chapter this block belongs to (you can create a new one) |
+| Module            | The module within that chapter (you can create a new one)    |
+| Position          | Where in the module this block appears (1-based)             |
+
+### Block Naming
+
+Block names for language curricula follow an automatic prefix based on the super block and block label. For example, a `learn` block in A2 English gets the prefix `en-a2-learn-`. When prompted, enter only the unique part of the name after the prefix.
+
+<Aside type="caution">
+
+Do not include the block label at the end of the name you enter. For example, if the prefix is `en-a2-learn-`, entering `greetings-learn` is incorrect.
+
+</Aside>
+
+### Creating a New Chapter
+
+Chapters are selected from a list during the block creation flow. If the chapter you need doesn't exist yet:
+
+- Run `pnpm run create-language-block`
+- Choose **-- Create new chapter --** when prompted
+
+You will then be asked for:
+
+| Prompt              | What to provide                                          |
+| ------------------- | -------------------------------------------------------- |
+| Chapter dashed name | A unique kebab-case identifier (e.g., `getting-started`) |
+| Chapter title       | A human-readable display title (e.g., `Getting Started`) |
+
+The chapter is created and the new block is placed inside it.
+
+### Creating a New Module
+
+Modules are selected from a list scoped to the chosen chapter during the block creation flow. If the module you need doesn't exist yet:
+
+- Run `pnpm run create-language-block`
+- Choose **-- Create new module --** when prompted
+
+You will be asked for:
+
+| Prompt             | What to provide                                                      |
+| ------------------ | -------------------------------------------------------------------- |
+| Module dashed name | A unique kebab-case identifier (e.g., `greetings-and-introductions`) |
+| Module title       | A human-readable display title (e.g., `Greetings and Introductions`) |
+
+## Renaming a Block
+
+The `rename-block` script renames an existing block and updates every file that references it, including the block metadata, the challenge directory, all superblock structures, and the locale intro file.
+
+To rename a block, run:
+
+```bash
+pnpm run rename-block
+```
+
+The script prompts you for:
+
+| Prompt                | What to provide                                           |
+| --------------------- | --------------------------------------------------------- |
+| Old block dashed name | The current dashed name of the block (must already exist) |
+| New display name      | The new human-readable title for the block                |
+| New dashed name       | The new kebab-case identifier for the block               |
+
+## Publishing New Content
+
+When a chapter, module, or block is created via the script, it is hidden by default, meaning it won't be visible on the production site until you choose to publish it.
+
+When you're ready to publish:
+
+- For blocks, change the `isUpcomingChange` property to `false` in the block's structure file (located in `curriculum/structure/blocks/`).
+- For chapters and modules, remove the `comingSoon` property from the super block structure file (located in `curriculum/structure/superblocks/`).
diff --git a/src/sidebar.ts b/src/sidebar.ts
index 1ba38b58..f457b15b 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -17,6 +17,7 @@ const sidebar = [
       'how-to-work-on-workshops',
       'how-to-setup-freecodecamp-mobile-app-locally',
       'how-to-work-on-localized-client-webapp',
+      'how-to-work-on-language-curricula',
       'how-to-add-playwright-tests',
       'how-to-work-on-the-docs-site',
       'how-to-open-a-pull-request',

From 492734cb0ad5ccebc4afe989ebe4040b29025e8c Mon Sep 17 00:00:00 2001
From: Huyen Nguyen <25715018+huyenltnguyen@users.noreply.github.com>
Date: Mon, 9 Mar 2026 19:29:07 +0700
Subject: [PATCH 2/4] document more scripts and add CJK writing convention

---
 .../how-to-work-on-language-curricula.mdx     | 202 ++++++++++++++++--
 1 file changed, 186 insertions(+), 16 deletions(-)

diff --git a/src/content/docs/how-to-work-on-language-curricula.mdx b/src/content/docs/how-to-work-on-language-curricula.mdx
index ae55bb6d..7e16c70c 100644
--- a/src/content/docs/how-to-work-on-language-curricula.mdx
+++ b/src/content/docs/how-to-work-on-language-curricula.mdx
@@ -7,15 +7,33 @@ sidebar:
 import { Steps } from '@astrojs/starlight/components';
 import { Aside } from '@astrojs/starlight/components';
 
-## Using Challenge Helper Scripts
+## Curriculum Structure
 
-All commands must be run from the `tools/challenge-helper-scripts` directory. To navigate to this directory, run:
+Language curricula follow a five-level hierarchy:
+
+- **Superblock** — The top-level course (e.g., _A2 English for Developers_)
+- **Chapter** — A broad thematic group within a superblock
+- **Module** — A focused topic within a chapter
+- **Block** — A set of tasks covering a specific lesson topic
+- **Task** — An individual challenge within a block (multiple-choice, fill-in-the-blank, quiz, etc.)
+
+For file structure, see [Curriculum File Structure](./curriculum-file-structure.mdx).
+
+## Modifying Curriculum Outer Layer
+
+To add or edit an outer layer (chapter, module, or block), we use the challenge helper scripts.
+
+### Creating a New Block
+
+<Aside type="note">
+
+Navigate to the `tools/challenge-helper-scripts` directory before running this script:
 
 ```bash
 cd tools/challenge-helper-scripts
 ```
 
-## Creating a New Block
+</Aside>
 
 To create a new block, run:
 
@@ -25,21 +43,21 @@ pnpm run create-language-block
 
 The script walks you through a series of prompts:
 
-| Prompt            | What to provide                                              |
-| ----------------- | ------------------------------------------------------------ |
-| Super block       | The super block this block belongs to (e.g., A2 English)     |
-| Block label       | The type of block: `practice`, `learn`, `quiz`, etc.         |
-| Block dashed name | A unique kebab-case identifier for the block                 |
-| Block title       | A human-readable title (defaults to the dashed name)         |
-| Help category     | The support category for this block's forum posts            |
-| Block layout      | The visual layout used to display challenges                 |
-| Chapter           | The chapter this block belongs to (you can create a new one) |
-| Module            | The module within that chapter (you can create a new one)    |
-| Position          | Where in the module this block appears (1-based)             |
+| Prompt            | What to provide                                                                                |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| Superblock        | The superblock this block belongs to (e.g., A2 English)                                        |
+| Block label       | The type of block: `practice`, `learn`, `quiz`, etc.                                           |
+| Block dashed name | A unique kebab-case identifier for the block (e.g., `en-a2-learn-greetings-and-introductions`) |
+| Block title       | A human-readable title (e.g., `Greetings and Introductions`)                                   |
+| Help category     | The support category for this block's forum posts                                              |
+| Block layout      | The visual layout used to display challenges                                                   |
+| Chapter           | The chapter this block belongs to (you can create a new one)                                   |
+| Module            | The module within that chapter (you can create a new one)                                      |
+| Position          | Where in the module this block appears (1-based)                                               |
 
 ### Block Naming
 
-Block names for language curricula follow an automatic prefix based on the super block and block label. For example, a `learn` block in A2 English gets the prefix `en-a2-learn-`. When prompted, enter only the unique part of the name after the prefix.
+Block names for language curricula follow an automatic prefix based on the superblock and block label. For example, a `learn` block in A2 English gets the prefix `en-a2-learn-`. When prompted, enter only the unique part of the name after the prefix.
 
 <Aside type="caution">
 
@@ -79,6 +97,16 @@ You will be asked for:
 
 ## Renaming a Block
 
+<Aside type="note">
+
+Navigate to the `tools/challenge-helper-scripts` directory before running this script:
+
+```bash
+cd tools/challenge-helper-scripts
+```
+
+</Aside>
+
 The `rename-block` script renames an existing block and updates every file that references it, including the block metadata, the challenge directory, all superblock structures, and the locale intro file.
 
 To rename a block, run:
@@ -95,6 +123,109 @@ The script prompts you for:
 | New display name      | The new human-readable title for the block                |
 | New dashed name       | The new kebab-case identifier for the block               |
 
+## Working with Tasks
+
+### Creating the Next Task
+
+<Aside type="note">
+
+Navigate to the `curriculum/` directory before running this script:
+
+```bash
+cd curriculum
+```
+
+</Aside>
+
+To add a new task at the end of a block, run:
+
+```bash
+pnpm run create-next-task
+```
+
+The script prompts you for:
+
+| Prompt                                        | What to provide                                                         |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| Task challenge type                           | The type of challenge: `multipleChoice`, `fillInTheBlank`, or `generic` |
+| Input type _(Chinese fill-in-the-blank only)_ | `pinyin-tone` or `pinyin-to-hanzi`                                      |
+
+After running, the script creates the task file, appends it to the `[block-name].json` file, and renumbers all tasks in the block.
+
+### Inserting a Task
+
+<Aside type="note">
+
+Navigate to the `curriculum/` directory before running this script:
+
+```bash
+cd curriculum
+```
+
+</Aside>
+
+To insert a new task before an existing one, run:
+
+```bash
+pnpm run insert-task
+```
+
+The script prompts you for:
+
+| Prompt                                          | What to provide                                                         |
+| ----------------------------------------------- | ----------------------------------------------------------------------- |
+| Which challenge should come AFTER this new one? | Select from the list of existing tasks                                  |
+| Task challenge type                             | The type of challenge: `multipleChoice`, `fillInTheBlank`, or `generic` |
+| Input type _(Chinese fill-in-the-blank only)_   | `pinyin-tone` or `pinyin-to-hanzi`                                      |
+
+After running, the script creates the task file, inserts it at the correct position in the `[block-name].json` file, and renumbers all tasks in the block.
+
+### Reordering Tasks
+
+<Aside type="note">
+
+Navigate to the `curriculum/` directory before running this script:
+
+```bash
+cd curriculum
+```
+
+</Aside>
+
+To resync task numbering after manual edits, run:
+
+```bash
+pnpm run reorder-tasks
+```
+
+The script takes no prompts. It reads the current task order from `[block-name].json` and updates all task file names and titles to match.
+
+### Deleting a Task
+
+<Aside type="note">
+
+Navigate to the `curriculum/` directory before running this script:
+
+```bash
+cd curriculum
+```
+
+</Aside>
+
+To delete a task from a block, run:
+
+```bash
+pnpm run delete-task
+```
+
+The script prompts you for:
+
+| Prompt                             | What to provide                        |
+| ---------------------------------- | -------------------------------------- |
+| Which challenge should be deleted? | Select from the list of existing tasks |
+
+After running, the script deletes the task file, removes it from `[block-name].json`, and renumbers the remaining tasks.
+
 ## Publishing New Content
 
 When a chapter, module, or block is created via the script, it is hidden by default, meaning it won't be visible on the production site until you choose to publish it.
@@ -102,4 +233,43 @@ When a chapter, module, or block is created via the script, it is hidden by defa
 When you're ready to publish:
 
 - For blocks, change the `isUpcomingChange` property to `false` in the block's structure file (located in `curriculum/structure/blocks/`).
-- For chapters and modules, remove the `comingSoon` property from the super block structure file (located in `curriculum/structure/superblocks/`).
+- For chapters and modules, remove the `comingSoon` property from the superblock structure file (located in `curriculum/structure/superblocks/`).
+
+## Working with CJK
+
+CJK language curricula (Chinese, Japanese, Korean) use a **base text — annotation** pair convention to link source characters to their pronunciation guide. For example:
+
+```
+`你好 (nǐ hǎo)`
+
+`こんにちは (konnichiwa)`
+
+`안녕하세요 (annyeonghaseyo)`
+```
+
+The challenge parser converts these inline pairs into HTML `<ruby>` elements for display.
+
+### Writing Convention
+
+The decision of where to split segments is ultimately up to the author, but the following are general guidelines:
+
+- Punctuation marks — place the annotation _before_ the punctuation
+- English words — do not annotate them
+- `BLANK` markers in fill-in-the-blank tasks
+
+Here are some examples:
+
+| Content type                            | Example                                           |
+| --------------------------------------- | ------------------------------------------------- |
+| Static text (basic)                     | `我叫王华 (wǒ jiào Wang Hua)。`                   |
+| Static text (with internal punctuation) | `你好 (nǐ hǎo)，我是王华 (wǒ shì Wang Hua)。`     |
+| Static text (with English)              | `我是 (wǒ shì) UI 设计师 (shè jì shī)。`          |
+| Fill-in-the-blank                       | `BLANK 好 (hǎo)，我 (wǒ) BLANK 王华 (Wang Hua)。` |
+
+### Chinese Input Types
+
+Chinese fill-in-the-blank tasks use one of two input types. You select the input type when creating a task with `create-next-task` or `insert-task`.
+
+- Pinyin-to-Hanzi: The learner types Pinyin with tone numbers (1–5). When a correctly typed syllable is entered, it converts to the corresponding Chinese character. Pressing backspace on a Chinese character reverts it to Pinyin and removes the last typed element (tone number or letter).
+
+- Pinyin Tone: The learner types Pinyin with tone numbers (1–5). Tone numbers are converted to tone marks in real time (e.g., typing `3` after `i` produces `ǐ`). Pressing backspace removes the last typed element (tone number or letter).

From 7ba60c9d18e6bbbc527edc8839877a8484892699 Mon Sep 17 00:00:00 2001
From: Huyen Nguyen <25715018+huyenltnguyen@users.noreply.github.com>
Date: Tue, 10 Mar 2026 03:24:27 +0700
Subject: [PATCH 3/4] add templates and minor improvements

---
 .../how-to-work-on-language-curricula.mdx     | 413 +++++++++++++++++-
 1 file changed, 394 insertions(+), 19 deletions(-)

diff --git a/src/content/docs/how-to-work-on-language-curricula.mdx b/src/content/docs/how-to-work-on-language-curricula.mdx
index 7e16c70c..4aa1df51 100644
--- a/src/content/docs/how-to-work-on-language-curricula.mdx
+++ b/src/content/docs/how-to-work-on-language-curricula.mdx
@@ -7,8 +7,6 @@ sidebar:
 import { Steps } from '@astrojs/starlight/components';
 import { Aside } from '@astrojs/starlight/components';
 
-## Curriculum Structure
-
 Language curricula follow a five-level hierarchy:
 
 - **Superblock** — The top-level course (e.g., _A2 English for Developers_)
@@ -17,7 +15,372 @@ Language curricula follow a five-level hierarchy:
 - **Block** — A set of tasks covering a specific lesson topic
 - **Task** — An individual challenge within a block (multiple-choice, fill-in-the-blank, quiz, etc.)
 
-For file structure, see [Curriculum File Structure](./curriculum-file-structure.mdx).
+For file structure, see [Curriculum File Structure](/curriculum-file-structure).
+
+## Task Template
+
+Tasks are written in markdown with frontmatter metadata. The boilerplate is automatically generated when you create a new task with the helper scripts.
+
+The following examples show the possible sections for each task type. Most tasks only use a subset of these sections.
+
+<details>
+  <summary>Multiple-Choice Question (Challenge Type 19)</summary>
+
+````
+---
+id: Unique identifier (alphanumerical, MongoDB_id)
+title: Task Title
+dashedName: kebab-case-name-for-task
+challengeType: 19
+lang: language code (e.g., `en-US`, `es`, `zh-CN`)
+videoId: YouTube video ID (if applicable)
+---
+
+# --description--
+
+Task description text.
+
+# --transcript--
+
+Transcript of the video, should only be used if the task has a video (`videoId` is defined).
+
+# --instructions--
+
+Task instructions text, in markdown.
+
+# --questions--
+
+## --text--
+
+Question text.
+
+## --answers--
+
+First option
+
+### --audio-id--
+
+Audio ID for this option (the name of the audio file, without the extension)
+
+### --feedback--
+
+Feedback shown when campers guess this answer
+
+---
+
+Second option
+
+### --audio-id--
+
+Audio ID for this option
+
+### --feedback--
+
+Feedback shown when campers guess this answer
+
+---
+
+Third option
+
+### --feedback--
+
+Feedback shown when campers guess this answer
+
+---
+
+Fourth option
+
+## --video-solution--
+
+The number for the correct answer goes here (1-based).
+
+# --explanation--
+
+Explanation text.
+
+# --scene--
+
+```json
+// # --scene-- can only consist of a single json object
+{
+  // Setup the scene. Properties not marked optional are required.
+  "setup": {
+    // Background file to start the scene. A list of scene asset filenames can be found here: https://github.com/freeCodeCamp/cdn/pull/233/files
+    "background": "company2-center.png",
+    // Array of all characters that will appear in the scene
+    "characters": [
+      {
+        // Name of character. See list of available characters in scene-assets.tsx
+        "character": "Maria",
+        // Where to start the character. Maria will start off screen to the left
+        "position": { "x": -25, "y": 0, "z": 1 }
+      },
+      {
+        "character": "Tom",
+        // Tom will start 70% from the left of the screen and 1.5 times regular size
+        "position": { "x": 70, "y": 0, "z": 1.5 },
+        // Optional, defaults to 1. Tom will start invisible
+        "opacity": 0
+      }
+    ],
+    "audio": {
+      // Audio filename
+      "filename": "1.1-1.mp3",
+      // Seconds after the scene starts before the audio starts playing
+      "startTime": 1.3,
+      // Optional. Timestamp of the audio file where it starts playing from.
+      "startTimestamp": 0,
+      // Optional. Timestamp of the audio file where is stops playing. If these two aren't used, the whole audio file will play.
+      "finishTimestamp": 8.4
+    },
+    // Optional, defaults to false. Use this for the long dialogues. It stops the accessibility icon from showing which gives campers the option to show or hide the dialogue text
+    "alwaysShowDialogue": true
+  },
+  // Array of commands that make up the scene
+  "commands": [
+    {
+      // Character that will have an action for this command
+      "character": "Maria",
+      // Optional, defaults to previous value. Maria will move to 25% from the left of the screen. The movement takes 0.5 seconds
+      "position": { "x": 25, "y": 0, "z": 1 },
+      // When the command will start. Zero seconds after the camper presses play
+      "startTime": 0
+    },
+    {
+      "character": "Tom",
+      // Optional, defaults to previous value. Tom will fade into view. The transition take 0.5 seconds. Movement and Opacity transitions take 0.5 seconds
+      "opacity": 1,
+      // Tom will fade into view 0.5 seconds into the scene (immediately after Maria finishes moving on screen)
+      "startTime": 0.5
+    },
+    {
+      "character": "Maria",
+      // When the command starts: Maria will start saying this line 1.3 seconds into the scene. Note that this is the same time as the audio.startTime above. It doesn't have to match that (maybe there's a pause at the beginning of the audio or something)
+      "startTime": 1.3,
+      // The character will stop moving their mouth at the finishTime
+      "finishTime": 4.95,
+      "dialogue": {
+        // Text that will appear if the dialogue is visible
+        "text": "Hello! You're the new graphic designer, right? I'm Maria, the team lead.",
+        // Where the dialogue text will be aligned. Can be 'left', 'center', or 'right'
+        "align": "left"
+      }
+    },
+    {
+      // background will change to this at 5.4 seconds into the scene
+      "background": "company2-breakroom.png",
+      "character": "Tom",
+      "startTime": 5.4,
+      "finishTime": 9.4,
+      "dialogue": {
+        "text": "Hi, that's right!  I'm Tom McKenzie. It's a pleasure to meet you.",
+        // Tom's text will be aligned to the right since he is on the right side of the screen
+        "align": "right"
+      }
+    },
+    {
+      "character": "Tom",
+      // Tom will fade to 0 opacity
+      "opacity": 0,
+      // I like to move characters off screen or fade them 0.5 second after the last talking command
+      "startTime": 9.9
+    },
+    {
+      "character": "Maria",
+      // Maria will slide back off the screen to the left
+      "position": { "x": -25, "y": 0, "z": 1 },
+      // The animation will stop playing 0.5 seconds after the 'finishTime' of the last command - or 0.5 seconds after 'startTime' if 'finishTime' isn't there.
+      "startTime": 10.4
+    }
+  ]
+}
+```
+````
+
+</details>
+
+<details>
+  <summary>Fill-in-the-Blank (Challenge Type 22)</summary>
+
+````
+---
+id: Unique identifier (alphanumerical, MongoDB_id)
+title: Task Title
+dashedName: kebab-case-name-for-task
+challengeType: 22
+lang: language code (e.g., `en-US`, `es`, `zh-CN`)
+---
+
+# --description--
+
+Task description text.
+
+# --instructions--
+
+Task instructions text, in markdown.
+
+# --fillInTheBlank--
+
+## --sentence--
+
+`The sentence with BLANK markers`
+
+## --blanks--
+
+`First blank answer`
+
+### --feedback--
+
+Feedback for the first blank
+
+---
+
+`Second blank answer`
+
+### --feedback--
+
+Feedback for the second blank
+
+# --explanation--
+
+Explanation text.
+
+# --scene--
+
+```json
+{
+  "setup": {
+    "background": "company2-center.png",
+    "characters": [
+      {
+        "character": "Maria",
+        "position": { "x": 50, "y": 25, "z": 1.5 },
+        "opacity": 0
+      }
+    ],
+    "audio": {
+      "filename": "1.1-1.mp3",
+      "startTime": 1,
+      "startTimestamp": 0,
+      "finishTimestamp": 4.5
+    }
+  },
+  "commands": [
+    {
+      "character": "Maria",
+      "opacity": 1,
+      "startTime": 0
+    },
+    {
+      "character": "Maria",
+      "startTime": 1,
+      "finishTime": 3.5,
+      "dialogue": {
+        "text": "Hello! Nice to meet you.",
+        "align": "center"
+      }
+    },
+    {
+      "character": "Maria",
+      "opacity": 0,
+      "startTime": 4
+    }
+  ]
+}
+```
+````
+
+</details>
+
+<details>
+  <summary>Review (Challenge Type 31)</summary>
+
+```
+---
+id: Unique identifier (alphanumerical, MongoDB_id)
+title: Task Title
+dashedName: kebab-case-name-for-task
+challengeType: 31
+lang: language code (e.g., `en-US`, `es`, `zh-CN`)
+---
+
+# --description--
+
+Review content in markdown.
+
+# --assignments--
+
+This will show a checkbox that campers have to check before completing a task.
+
+---
+
+This will show another checkbox that campers have to check before completing a challenge.
+```
+
+</details>
+
+<details>
+  <summary>Quiz (Challenge Type 8)</summary>
+
+````
+---
+id: Unique identifier (alphanumerical, MongoDB_id)
+title: Quiz Title
+dashedName: kebab-case-name-for-quiz
+challengeType: 8
+lang: language code (e.g., `en-US`, `es`, `zh-CN`)
+---
+
+# --description--
+
+Quiz description text.
+
+# --quizzes--
+
+## --quiz--
+
+### --question--
+
+#### --text--
+
+Question text.
+
+#### --audio--
+
+```json
+{
+  "audio": {
+    "filename": "audio-filename.mp3",
+    "startTimestamp": 0,
+    "finishTimestamp": 4.5
+  },
+  "transcript": [
+    {
+      "character": "Character Name",
+      "text": "Audio transcript text."
+    }
+  ]
+}
+```
+
+#### --distractors--
+
+First distractor option
+
+---
+
+Second distractor option
+
+---
+
+Third distractor option
+
+#### --answer--
+
+The correct answer
+````
+
+</details>
 
 ## Modifying Curriculum Outer Layer
 
@@ -95,6 +458,21 @@ You will be asked for:
 | Module dashed name | A unique kebab-case identifier (e.g., `greetings-and-introductions`) |
 | Module title       | A human-readable display title (e.g., `Greetings and Introductions`) |
 
+## Renaming a Chapter
+
+To rename a chapter, update the chapter's dashed name and display name in the following files:
+
+- `curriculum/structure/superblocks/[superblock-name].json`
+- `client/i18n/locales/english/intro.json`
+- `packages/shared/src/config/chapters.ts`
+
+## Renaming a Module
+
+To rename a module, update the module's dashed name and display name in the following files:
+
+- `curriculum/structure/superblocks/[superblock-name].json`
+- `client/i18n/locales/english/intro.json`
+
 ## Renaming a Block
 
 <Aside type="note">
@@ -232,39 +610,36 @@ When a chapter, module, or block is created via the script, it is hidden by defa
 
 When you're ready to publish:
 
-- For blocks, change the `isUpcomingChange` property to `false` in the block's structure file (located in `curriculum/structure/blocks/`).
-- For chapters and modules, remove the `comingSoon` property from the superblock structure file (located in `curriculum/structure/superblocks/`).
+- For blocks, change the `isUpcomingChange` property to `false` in the block's structure file (`curriculum/structure/blocks/[block-name].json`).
+- For chapters and modules, remove the `comingSoon` property from the superblock structure file (`curriculum/structure/superblocks/[superblock-name].json`).
 
 ## Working with CJK
 
 CJK language curricula (Chinese, Japanese, Korean) use a **base text — annotation** pair convention to link source characters to their pronunciation guide. For example:
 
-```
-`你好 (nǐ hǎo)`
-
-`こんにちは (konnichiwa)`
-
-`안녕하세요 (annyeonghaseyo)`
-```
+- `你好 (nǐ hǎo)`
+- `こんにちは (konnichiwa)` or `こ (ko) ん (n) に (ni) ち (chi) は (wa)`
+- `안녕하세요 (annyeonghaseyo)` or `안 (an) 녕 (nyeong) 하 (ha) 세 (se) 요 (yo)`
 
 The challenge parser converts these inline pairs into HTML `<ruby>` elements for display.
 
-### Writing Convention
+### CJK Writing Convention
 
 The decision of where to split segments is ultimately up to the author, but the following are general guidelines:
 
-- Punctuation marks — place the annotation _before_ the punctuation
-- English words — do not annotate them
-- `BLANK` markers in fill-in-the-blank tasks
+- Punctuation marks: place the annotation _before_ the punctuation
+- English words: do not annotate them
+- `BLANK` markers in fill-in-the-blank tasks: do not annotate them
+- Lowercase annotations: use lowercase for annotations, even if the base text is a proper noun or is the first word of a sentence
 
 Here are some examples:
 
 | Content type                            | Example                                           |
 | --------------------------------------- | ------------------------------------------------- |
-| Static text (basic)                     | `我叫王华 (wǒ jiào Wang Hua)。`                   |
-| Static text (with internal punctuation) | `你好 (nǐ hǎo)，我是王华 (wǒ shì Wang Hua)。`     |
+| Static text (basic)                     | `我叫王华 (wǒ jiào wáng huá)。`                   |
+| Static text (with internal punctuation) | `你好 (nǐ hǎo)，我是王华 (wǒ shì wáng huá)。`     |
 | Static text (with English)              | `我是 (wǒ shì) UI 设计师 (shè jì shī)。`          |
-| Fill-in-the-blank                       | `BLANK 好 (hǎo)，我 (wǒ) BLANK 王华 (Wang Hua)。` |
+| Fill-in-the-blank                       | `BLANK 好 (hǎo)，我 (wǒ) BLANK 王华 (wáng huá)。` |
 
 ### Chinese Input Types
 

From 5c57603592ee3a633a780d3bf249b0a4e9361386 Mon Sep 17 00:00:00 2001
From: Huyen Nguyen <25715018+huyenltnguyen@users.noreply.github.com>
Date: Wed, 11 Mar 2026 20:01:43 +0700
Subject: [PATCH 4/4] add assets addition steps

---
 .../how-to-work-on-language-curricula.mdx     | 28 +++++++++++++------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/src/content/docs/how-to-work-on-language-curricula.mdx b/src/content/docs/how-to-work-on-language-curricula.mdx
index 4aa1df51..48757cc3 100644
--- a/src/content/docs/how-to-work-on-language-curricula.mdx
+++ b/src/content/docs/how-to-work-on-language-curricula.mdx
@@ -550,11 +550,11 @@ pnpm run insert-task
 
 The script prompts you for:
 
-| Prompt                                          | What to provide                                                         |
-| ----------------------------------------------- | ----------------------------------------------------------------------- |
-| Which challenge should come AFTER this new one? | Select from the list of existing tasks                                  |
-| Task challenge type                             | The type of challenge: `multipleChoice`, `fillInTheBlank`, or `generic` |
-| Input type _(Chinese fill-in-the-blank only)_   | `pinyin-tone` or `pinyin-to-hanzi`                                      |
+| Prompt                                        | What to provide                                                         |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| Which task should come AFTER this new one?    | Select from the list of existing tasks                                  |
+| Task challenge type                           | The type of challenge: `multipleChoice`, `fillInTheBlank`, or `generic` |
+| Input type _(Chinese fill-in-the-blank only)_ | `pinyin-tone` or `pinyin-to-hanzi`                                      |
 
 After running, the script creates the task file, inserts it at the correct position in the `[block-name].json` file, and renumbers all tasks in the block.
 
@@ -604,13 +604,25 @@ The script prompts you for:
 
 After running, the script deletes the task file, removes it from `[block-name].json`, and renumbers the remaining tasks.
 
+## Adding Scene Assets
+
+Scene assets (backgrounds, characters, and audio) are stored in the `cdn` repository. To add new assets:
+
+- Create a PR to upload the files to the `cdn` repository
+  - If the asset is an image, upload it to https://github.com/freeCodeCamp/cdn/tree/main/build/curriculum/english/animation-assets/images
+  - If the asset is audio, upload it to https://github.com/freeCodeCamp/cdn/tree/main/build/curriculum/english/animation-assets/sounds
+- Create a PR to add the asset to the main repository:
+  - Add the new filename or character name to `curriculum/schema/scene-assets.js`
+  - Update the snapshot test by running `pnpm --filter @freecodecamp/curriculum exec vitest run schema/challenge-schema.test.mjs -u`
+  - The `curriculum/schema/__snapshots__/challenge-schema.test.mjs.snap` file should now be automatically updated with the new asset. Include this change in your PR.
+
 ## Publishing New Content
 
 When a chapter, module, or block is created via the script, it is hidden by default, meaning it won't be visible on the production site until you choose to publish it.
 
 When you're ready to publish:
 
-- For blocks, change the `isUpcomingChange` property to `false` in the block's structure file (`curriculum/structure/blocks/[block-name].json`).
+- For blocks, change the `isUpcomingChange` property to `false` in the block structure file (`curriculum/structure/blocks/[block-name].json`).
 - For chapters and modules, remove the `comingSoon` property from the superblock structure file (`curriculum/structure/superblocks/[superblock-name].json`).
 
 ## Working with CJK
@@ -621,7 +633,7 @@ CJK language curricula (Chinese, Japanese, Korean) use a **base text — annotat
 - `こんにちは (konnichiwa)` or `こ (ko) ん (n) に (ni) ち (chi) は (wa)`
 - `안녕하세요 (annyeonghaseyo)` or `안 (an) 녕 (nyeong) 하 (ha) 세 (se) 요 (yo)`
 
-The challenge parser converts these inline pairs into HTML `<ruby>` elements for display.
+The challenge parser converts these pairs into HTML `<ruby>` elements for display.
 
 ### CJK Writing Convention
 
@@ -630,7 +642,7 @@ The decision of where to split segments is ultimately up to the author, but the
 - Punctuation marks: place the annotation _before_ the punctuation
 - English words: do not annotate them
 - `BLANK` markers in fill-in-the-blank tasks: do not annotate them
-- Lowercase annotations: use lowercase for annotations, even if the base text is a proper noun or is the first word of a sentence
+- Lowercase annotations: always use lowercase for annotations, even if the base text is a proper noun or is the first word of a sentence
 
 Here are some examples: