diff --git a/scripts/check-metadata.js b/scripts/check-metadata.js
index 6505247b..8409ff43 100644
--- a/scripts/check-metadata.js
+++ b/scripts/check-metadata.js
@@ -8,12 +8,12 @@
 const fs = require('fs');
 const path = require('path');
 
-// Load the mapping file to get all icon names
-const mappingPath = path.join(__dirname, '..', 'src', 'template', 'mapping.json');
+// Load the icons directory to get all icon names
+const iconsDir = path.join(__dirname, '..', 'src', 'icons');
 const metadataPath = path.join(__dirname, '..', 'src', 'template', 'metadata.json');
 
-if (!fs.existsSync(mappingPath)) {
-    console.error('Error: mapping.json not found at', mappingPath);
+if (!fs.existsSync(iconsDir)) {
+    console.error('Error: icons directory not found at', iconsDir);
     process.exit(1);
 }
 
@@ -22,17 +22,15 @@ if (!fs.existsSync(metadataPath)) {
     process.exit(1);
 }
 
-const mapping = JSON.parse(fs.readFileSync(mappingPath, 'utf8'));
 const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
 
-// Collect all unique icon names from mapping
-const allIconNames = new Set();
-Object.values(mapping).forEach(aliases => {
-    // For each code point, add the first alias (primary name)
-    if (aliases && aliases.length > 0) {
-        allIconNames.add(aliases[0]);
-    }
-});
+// Collect all icon names from the actual SVG files. Metadata is keyed by the
+// SVG file name, which is the canonical identity for each icon.
+const allIconNames = new Set(
+    fs.readdirSync(iconsDir)
+        .filter(file => file.endsWith('.svg'))
+        .map(file => path.basename(file, '.svg'))
+);
 
 // Find icons without metadata
 const missingMetadata = [];
diff --git a/scripts/svg-sprite.js b/scripts/svg-sprite.js
index 7b3688a6..81a7f377 100644
--- a/scripts/svg-sprite.js
+++ b/scripts/svg-sprite.js
@@ -65,31 +65,37 @@ let processedFiles = 0;
 const processedIcons = new Set();
 
 Object.entries(mapping).forEach(([code, aliases]) => {
-  // Use the first alias as the primary SVG file name
-  const primaryAlias = aliases[0];
-  
+  // The SVG file backing this icon may be named after any of its aliases,
+  // not necessarily the primary one, so pick whichever file actually exists.
+  const sourceAlias = aliases.find(alias =>
+    fs.existsSync(path.resolve(iconsDir, `${alias}.svg`))
+  );
+
+  if (!sourceAlias) {
+    console.warn(`Warning: no SVG file found for code ${code} (aliases: ${aliases.join(", ")})`);
+    return;
+  }
+
   // Skip if we've already processed this icon
-  if (processedIcons.has(primaryAlias)) {
+  if (processedIcons.has(sourceAlias)) {
     return;
   }
-  
+
   // Use path.resolve for cross-platform compatibility
-  const file = path.resolve(iconsDir, `${primaryAlias}.svg`);
-
-  if (fs.existsSync(file)) {
-    processedFiles++;
-    processedIcons.add(primaryAlias);
-    
-    // Add sprite entries for all aliases of this icon
-    for (const name of aliases) {
-      // Use path.resolve for cross-platform compatibility
-      const svgPath = path.resolve(iconsDir, `${name}.svg`);
-      spriter.add(
-        svgPath,
-        name + ".svg",
-        fs.readFileSync(file, "utf-8"),
-      );
-    }
+  const file = path.resolve(iconsDir, `${sourceAlias}.svg`);
+
+  processedFiles++;
+  processedIcons.add(sourceAlias);
+
+  // Add sprite entries for all aliases of this icon
+  for (const name of aliases) {
+    // Use path.resolve for cross-platform compatibility
+    const svgPath = path.resolve(iconsDir, `${name}.svg`);
+    spriter.add(
+      svgPath,
+      name + ".svg",
+      fs.readFileSync(file, "utf-8"),
+    );
   }
 });
 
diff --git a/src/template/mapping.json b/src/template/mapping.json
index 20cb1f8d..365f8374 100644
--- a/src/template/mapping.json
+++ b/src/template/mapping.json
@@ -14,8 +14,8 @@
     "repo-delete"
   ],
   "60003": [
-    "gist-fork",
-    "repo-forked"
+    "repo-forked",
+    "gist-fork"
   ],
   "60004": [
     "git-pull-request",
@@ -45,30 +45,30 @@
     "mirror-public"
   ],
   "60010": [
+    "star-empty",
     "star",
     "star-add",
-    "star-delete",
-    "star-empty"
+    "star-delete"
   ],
   "60011": [
     "comment",
     "comment-add"
   ],
   "60012": [
-    "alert",
-    "warning"
+    "warning",
+    "alert"
   ],
   "60013": [
     "search",
     "search-save"
   ],
   "60014": [
-    "log-out",
-    "sign-out"
+    "sign-out",
+    "log-out"
   ],
   "60015": [
-    "log-in",
-    "sign-in"
+    "sign-in",
+    "log-in"
   ],
   "60016": [
     "eye",
@@ -96,9 +96,9 @@
     "issue-opened"
   ],
   "60021": [
+    "lock",
     "gist-private",
     "git-fork-private",
-    "lock",
     "mirror-private"
   ],
   "60022": [
@@ -107,12 +107,12 @@
     "x"
   ],
   "60023": [
-    "repo-sync",
-    "sync"
+    "sync",
+    "repo-sync"
   ],
   "60024": [
-    "clone",
-    "desktop-download"
+    "desktop-download",
+    "clone"
   ],
   "60025": [
     "beaker",
@@ -126,13 +126,13 @@
     "file"
   ],
   "60028": [
-    "more",
     "ellipsis",
+    "more",
     "kebab-horizontal"
   ],
   "60029": [
-    "mail-reply",
-    "reply"
+    "reply",
+    "mail-reply"
   ],
   "60030": [
     "organization",
@@ -161,9 +161,9 @@
     "symbol-folder"
   ],
   "60036": [
+    "github",
     "logo-github",
-    "mark-github",
-    "github"
+    "mark-github"
   ],
   "60037": [
     "terminal",
@@ -171,25 +171,25 @@
     "repl"
   ],
   "60038": [
-    "zap",
-    "symbol-event"
+    "symbol-event",
+    "zap"
   ],
   "60039": [
     "error",
     "stop"
   ],
   "60040": [
-    "variable",
-    "symbol-variable"
+    "symbol-variable",
+    "variable"
   ],
   "60042": [
-    "array",
-    "symbol-array"
+    "symbol-array",
+    "array"
   ],
   "60043": [
+    "symbol-namespace",
     "symbol-module",
     "symbol-package",
-    "symbol-namespace",
     "symbol-object"
   ],
   "60044": [
@@ -218,8 +218,8 @@
     "symbol-text"
   ],
   "60052": [
-    "symbol-reference",
-    "go-to-file"
+    "go-to-file",
+    "symbol-reference"
   ],
   "60053": [
     "symbol-enum",
@@ -344,8 +344,8 @@
     "chrome-restore"
   ],
   "60092": [
-    "circle-outline",
     "circle",
+    "circle-outline",
     "debug-breakpoint-unverified",
     "terminal-decoration-incomplete"
   ],
diff --git a/src/template/metadata.json b/src/template/metadata.json
index c03a14fb..5a92b586 100644
--- a/src/template/metadata.json
+++ b/src/template/metadata.json
@@ -82,7 +82,7 @@
     "category": "ai",
     "description": "AI agent or bot (compact 12x12 variant)"
   },
-  "alert": {
+  "warning": {
     "tags": [
       "warning",
       "error",
@@ -106,7 +106,7 @@
     "category": "file",
     "description": "Archive or package items"
   },
-  "array": {
+  "symbol-array": {
     "tags": [
       "list",
       "collection",
@@ -930,7 +930,7 @@
     "category": "shape",
     "description": "Large filled circle"
   },
-  "circle-outline": {
+  "circle": {
     "tags": [
       "round",
       "shape",
@@ -1061,7 +1061,7 @@
     "category": "general",
     "description": "Clock face showing time"
   },
-  "clone": {
+  "desktop-download": {
     "tags": [
       "copy",
       "duplicate",
@@ -2748,7 +2748,7 @@
     "category": "git",
     "description": "GitHub Gist"
   },
-  "gist-fork": {
+  "repo-forked": {
     "tags": [
       "copy",
       "branch",
@@ -2761,7 +2761,7 @@
     "category": "git",
     "description": "Fork Gist"
   },
-  "gist-private": {
+  "lock": {
     "tags": [
       "lock",
       "secret",
@@ -3939,7 +3939,7 @@
     "category": "security",
     "description": "Small lock"
   },
-  "log-in": {
+  "sign-in": {
     "tags": [
       "sign in",
       "enter",
@@ -3950,7 +3950,7 @@
     "category": "user",
     "description": "Log in"
   },
-  "log-out": {
+  "sign-out": {
     "tags": [
       "sign out",
       "exit",
@@ -3961,7 +3961,7 @@
     "category": "user",
     "description": "Log out"
   },
-  "logo-github": {
+  "github": {
     "tags": [
       "brand",
       "cat",
@@ -4004,7 +4004,7 @@
     "category": "communication",
     "description": "Read mail"
   },
-  "mail-reply": {
+  "reply": {
     "tags": [
       "email",
       "respond",
@@ -4191,7 +4191,7 @@
     "category": "action",
     "description": "Mirror or reflect"
   },
-  "more": {
+  "ellipsis": {
     "tags": [
       "ellipsis",
       "menu",
@@ -5038,7 +5038,7 @@
     "category": "git",
     "description": "Selected repository"
   },
-  "repo-sync": {
+  "sync": {
     "tags": [
       "git",
       "refresh",
@@ -5644,7 +5644,7 @@
     "category": "general",
     "description": "Squirrel"
   },
-  "star": {
+  "star-empty": {
     "tags": [
       "favorite",
       "bookmark",
@@ -5873,7 +5873,7 @@
     "category": "symbol",
     "description": "Miscellaneous symbol"
   },
-  "symbol-module": {
+  "symbol-namespace": {
     "tags": [
       "code",
       "package",
@@ -5928,7 +5928,7 @@
     "category": "symbol",
     "description": "Property symbol"
   },
-  "symbol-reference": {
+  "go-to-file": {
     "tags": [
       "code",
       "link",
@@ -6444,7 +6444,7 @@
     "category": "status",
     "description": "Unverified"
   },
-  "variable": {
+  "symbol-variable": {
     "tags": [
       "code",
       "value",
@@ -6789,7 +6789,7 @@
     "category": "git",
     "description": "Git worktree (small variant)"
   },
-  "zap": {
+  "symbol-event": {
     "tags": [
       "flash",
       "electric",