@codecademy/gamut

Index: package/bin/lib/design.mjs
===================================================================
--- package/bin/lib/design.mjs
+++ package/bin/lib/design.mjs
@@ -1,5 +1,5 @@
-import { copyFile, stat } from 'node:fs/promises';
+import { readFile, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 /** @type {Record<string, { sourceFile: string, label: string }>} */
 const THEME_ALIASES = {
@@ -49,9 +49,9 @@
  * @param {{ force?: boolean }} [options]
  * @returns {Promise<{ dest: string, label: string }>}
  */
 export async function installDesignMd(sourceRoot, cwd, theme, options = {}) {
-  const { sourceFile, label } = resolveTheme(theme);
+  const { sourceFile, label, alias } = resolveTheme(theme);
   const src = join(sourceRoot, sourceFile);
   const dest = join(cwd, 'DESIGN.md');
 
   const srcStat = await stat(src).catch(() => null);
@@ -65,7 +65,17 @@
       `DESIGN.md already exists at ${dest}. Use --force to overwrite, or remove it first.`
     );
   }
 
-  await copyFile(src, dest);
+  const version = await readFile(join(sourceRoot, '..', 'package.json'), 'utf8')
+    .then((raw) => JSON.parse(raw).version ?? 'unknown')
+    .catch(() => 'unknown');
+
+  const header =
+    `<!-- Generated by @codecademy/gamut@${version}.\n` +
+    `     Do not edit this file directly — to update, re-run:\n` +
+    `     gamut plugin install --theme ${alias} --force -->\n`;
+
+  const content = await readFile(src, 'utf8');
+  await writeFile(dest, header + content, 'utf8');
   return { dest, label };
 }