blume 1.7.3 → 2.0.0

package/src/core/ui-packs/it.ts

@@ -41,10 +41,11 @@ export const it: UIStringsOverride = {
   banner: { dismiss: "Chiudi l'annuncio" },
   changelog: {
     description: "Aggiornamenti del prodotto e note di rilascio.",
-    showReleases: "Mostra le versioni {version}",
     title: "Registro delle modifiche",
   },
   content: {
+    copyColor: "Copia il colore {name} {value}",
+    copyPrompt: "Copia prompt",
     diagramError: "Impossibile visualizzare questo diagramma.",
   },
   feedback: {
@@ -62,6 +63,7 @@ export const it: UIStringsOverride = {
     featured: "In evidenza",
     githubRepository: "Repository GitHub",
     navigation: "Navigazione",
+    opensInNewTab: "Si apre in una nuova scheda",
     primary: "Principale",
     sections: "Sezioni",
     toggleNavigation: "Mostra o nascondi la navigazione",

package/src/core/ui-packs/ja.ts

@@ -42,10 +42,11 @@ export const ja: UIStringsOverride = {
   banner: { dismiss: "お知らせを閉じる" },
   changelog: {
     description: "製品のアップデートとリリースノート。",
-    showReleases: "{version} のリリースを表示",
     title: "変更履歴",
   },
   content: {
+    copyColor: "カラー {name}（{value}）をコピー",
+    copyPrompt: "プロンプトをコピー",
     diagramError: "この図を表示できませんでした。",
   },
   feedback: {
@@ -63,6 +64,7 @@ export const ja: UIStringsOverride = {
     featured: "注目",
     githubRepository: "GitHub リポジトリ",
     navigation: "ナビゲーション",
+    opensInNewTab: "新しいタブで開きます",
     primary: "メイン",
     sections: "セクション",
     toggleNavigation: "ナビゲーションを切り替え",

package/src/core/ui-packs/ko.ts

@@ -42,10 +42,11 @@ export const ko: UIStringsOverride = {
   banner: { dismiss: "공지 닫기" },
   changelog: {
     description: "제품 업데이트 및 릴리스 노트.",
-    showReleases: "{version} 릴리스 보기",
     title: "변경 로그",
   },
   content: {
+    copyColor: "{name} 색상 {value} 복사",
+    copyPrompt: "프롬프트 복사",
     diagramError: "이 다이어그램을 표시할 수 없습니다.",
   },
   feedback: {
@@ -63,6 +64,7 @@ export const ko: UIStringsOverride = {
     featured: "추천",
     githubRepository: "GitHub 저장소",
     navigation: "탐색",
+    opensInNewTab: "새 탭에서 열림",
     primary: "기본",
     sections: "섹션",
     toggleNavigation: "탐색 전환",

package/src/core/ui-packs/nl.ts

@@ -42,10 +42,13 @@ export const nl: UIStringsOverride = {
   banner: { dismiss: "Aankondiging sluiten" },
   changelog: {
     description: "Productupdates en releaseopmerkingen.",
-    showReleases: "Releases voor {version} tonen",
     title: "Wijzigingslogboek",
   },
-  content: { diagramError: "Dit diagram kon niet worden weergegeven." },
+  content: {
+    copyColor: "Kleur {name} {value} kopiëren",
+    copyPrompt: "Prompt kopiëren",
+    diagramError: "Dit diagram kon niet worden weergegeven.",
+  },
   feedback: {
     no: "Nee",
     question: "Was deze pagina nuttig?",
@@ -61,6 +64,7 @@ export const nl: UIStringsOverride = {
     featured: "Uitgelicht",
     githubRepository: "GitHub-repository",
     navigation: "Navigatie",
+    opensInNewTab: "Opent in een nieuw tabblad",
     primary: "Primair",
     sections: "Secties",
     toggleNavigation: "Navigatie tonen of verbergen",

package/src/core/ui-packs/no.ts

@@ -42,10 +42,13 @@ export const no: UIStringsOverride = {
   banner: { dismiss: "Lukk kunngjøringen" },
   changelog: {
     description: "Produktoppdateringer og utgivelsesnotater.",
-    showReleases: "Vis utgivelser for {version}",
     title: "Endringslogg",
   },
-  content: { diagramError: "Kunne ikke vise dette diagrammet." },
+  content: {
+    copyColor: "Kopier fargen {name} {value}",
+    copyPrompt: "Kopier prompt",
+    diagramError: "Kunne ikke vise dette diagrammet.",
+  },
   feedback: {
     no: "Nei",
     question: "Var denne siden nyttig?",
@@ -61,6 +64,7 @@ export const no: UIStringsOverride = {
     featured: "Utvalgt",
     githubRepository: "GitHub-repositorium",
     navigation: "Navigasjon",
+    opensInNewTab: "Åpnes i en ny fane",
     primary: "Primær",
     sections: "Seksjoner",
     toggleNavigation: "Vis eller skjul navigasjonen",

package/src/core/ui-packs/pl.ts

@@ -42,10 +42,13 @@ export const pl: UIStringsOverride = {
   banner: { dismiss: "Zamknij ogłoszenie" },
   changelog: {
     description: "Aktualizacje produktu i informacje o wydaniach.",
-    showReleases: "Pokaż wydania {version}",
     title: "Dziennik zmian",
   },
-  content: { diagramError: "Nie udało się wyświetlić tego diagramu." },
+  content: {
+    copyColor: "Kopiuj kolor {name} {value}",
+    copyPrompt: "Kopiuj prompt",
+    diagramError: "Nie udało się wyświetlić tego diagramu.",
+  },
   feedback: {
     no: "Nie",
     question: "Czy ta strona była pomocna?",
@@ -61,6 +64,7 @@ export const pl: UIStringsOverride = {
     featured: "Polecane",
     githubRepository: "Repozytorium GitHub",
     navigation: "Nawigacja",
+    opensInNewTab: "Otwiera się w nowej karcie",
     primary: "Główne",
     sections: "Sekcje",
     toggleNavigation: "Przełącz nawigację",

package/src/core/ui-packs/pt-br.ts

@@ -42,10 +42,11 @@ export const ptBR: UIStringsOverride = {
   banner: { dismiss: "Fechar o anúncio" },
   changelog: {
     description: "Atualizações do produto e notas de lançamento.",
-    showReleases: "Mostrar versões {version}",
     title: "Registro de alterações",
   },
   content: {
+    copyColor: "Copiar a cor {name} {value}",
+    copyPrompt: "Copiar prompt",
     diagramError: "Não foi possível renderizar este diagrama.",
   },
   feedback: {
@@ -63,6 +64,7 @@ export const ptBR: UIStringsOverride = {
     featured: "Em destaque",
     githubRepository: "Repositório do GitHub",
     navigation: "Navegação",
+    opensInNewTab: "Abre em uma nova aba",
     primary: "Principal",
     sections: "Seções",
     toggleNavigation: "Mostrar ou ocultar a navegação",

package/src/core/ui-packs/pt.ts

@@ -42,10 +42,11 @@ export const pt: UIStringsOverride = {
   banner: { dismiss: "Fechar o anúncio" },
   changelog: {
     description: "Atualizações do produto e notas de lançamento.",
-    showReleases: "Mostrar versões {version}",
     title: "Registo de alterações",
   },
   content: {
+    copyColor: "Copiar a cor {name} {value}",
+    copyPrompt: "Copiar prompt",
     diagramError: "Não foi possível apresentar este diagrama.",
   },
   feedback: {
@@ -63,6 +64,7 @@ export const pt: UIStringsOverride = {
     featured: "Em destaque",
     githubRepository: "Repositório do GitHub",
     navigation: "Navegação",
+    opensInNewTab: "Abre num novo separador",
     primary: "Principal",
     sections: "Secções",
     toggleNavigation: "Mostrar ou ocultar a navegação",

package/src/core/ui-packs/ro.ts

@@ -42,10 +42,13 @@ export const ro: UIStringsOverride = {
   banner: { dismiss: "Închide anunțul" },
   changelog: {
     description: "Actualizări ale produsului și note de lansare.",
-    showReleases: "Afișează lansările {version}",
     title: "Jurnal de modificări",
   },
-  content: { diagramError: "Nu s-a putut reda această diagramă." },
+  content: {
+    copyColor: "Copiază culoarea {name} {value}",
+    copyPrompt: "Copiază promptul",
+    diagramError: "Nu s-a putut reda această diagramă.",
+  },
   feedback: {
     no: "Nu",
     question: "Ți-a fost utilă această pagină?",
@@ -61,6 +64,7 @@ export const ro: UIStringsOverride = {
     featured: "Recomandate",
     githubRepository: "Depozit GitHub",
     navigation: "Navigare",
+    opensInNewTab: "Se deschide într-o filă nouă",
     primary: "Principal",
     sections: "Secțiuni",
     toggleNavigation: "Comută navigarea",

package/src/core/ui-packs/ru.ts

@@ -42,10 +42,13 @@ export const ru: UIStringsOverride = {
   banner: { dismiss: "Закрыть объявление" },
   changelog: {
     description: "Обновления продукта и примечания к выпускам.",
-    showReleases: "Показать выпуски {version}",
     title: "Журнал изменений",
   },
-  content: { diagramError: "Не удалось отобразить эту диаграмму." },
+  content: {
+    copyColor: "Скопировать цвет {name} {value}",
+    copyPrompt: "Скопировать промпт",
+    diagramError: "Не удалось отобразить эту диаграмму.",
+  },
   feedback: {
     no: "Нет",
     question: "Эта страница была полезной?",
@@ -61,6 +64,7 @@ export const ru: UIStringsOverride = {
     featured: "Рекомендуемое",
     githubRepository: "Репозиторий GitHub",
     navigation: "Навигация",
+    opensInNewTab: "Открывается в новой вкладке",
     primary: "Основное",
     sections: "Разделы",
     toggleNavigation: "Переключить навигацию",

package/src/core/ui-packs/sk.ts

@@ -41,10 +41,13 @@ export const sk: UIStringsOverride = {
   banner: { dismiss: "Zavrieť oznámenie" },
   changelog: {
     description: "Novinky produktu a poznámky k vydaniu.",
-    showReleases: "Zobraziť vydania {version}",
     title: "Zoznam zmien",
   },
-  content: { diagramError: "Tento diagram sa nepodarilo vykresliť." },
+  content: {
+    copyColor: "Kopírovať farbu {name} {value}",
+    copyPrompt: "Kopírovať prompt",
+    diagramError: "Tento diagram sa nepodarilo vykresliť.",
+  },
   feedback: {
     no: "Nie",
     question: "Bola táto stránka užitočná?",
@@ -60,6 +63,7 @@ export const sk: UIStringsOverride = {
     featured: "Odporúčané",
     githubRepository: "Repozitár na GitHube",
     navigation: "Navigácia",
+    opensInNewTab: "Otvorí sa na novej karte",
     primary: "Hlavné",
     sections: "Sekcie",
     toggleNavigation: "Prepnúť navigáciu",

package/src/core/ui-packs/sr.ts

@@ -41,10 +41,13 @@ export const sr: UIStringsOverride = {
   banner: { dismiss: "Затвори обавештење" },
   changelog: {
     description: "Ажурирања производа и белешке о издањима.",
-    showReleases: "Прикажи издања {version}",
     title: "Дневник измена",
   },
-  content: { diagramError: "Није могуће приказати овај дијаграм." },
+  content: {
+    copyColor: "Копирај боју {name} {value}",
+    copyPrompt: "Копирај упит",
+    diagramError: "Није могуће приказати овај дијаграм.",
+  },
   feedback: {
     no: "Не",
     question: "Да ли вам је ова страница помогла?",
@@ -60,6 +63,7 @@ export const sr: UIStringsOverride = {
     featured: "Истакнуто",
     githubRepository: "GitHub репозиторијум",
     navigation: "Навигација",
+    opensInNewTab: "Отвара се у новој картици",
     primary: "Главна",
     sections: "Одељци",
     toggleNavigation: "Отвори или затвори навигацију",

package/src/core/ui-packs/sv.ts

@@ -42,10 +42,13 @@ export const sv: UIStringsOverride = {
   banner: { dismiss: "Stäng meddelandet" },
   changelog: {
     description: "Produktuppdateringar och versionsinformation.",
-    showReleases: "Visa utgåvor för {version}",
     title: "Ändringslogg",
   },
-  content: { diagramError: "Det här diagrammet kunde inte visas." },
+  content: {
+    copyColor: "Kopiera färgen {name} {value}",
+    copyPrompt: "Kopiera prompt",
+    diagramError: "Det här diagrammet kunde inte visas.",
+  },
   feedback: {
     no: "Nej",
     question: "Var den här sidan till hjälp?",
@@ -61,6 +64,7 @@ export const sv: UIStringsOverride = {
     featured: "Utvalda",
     githubRepository: "GitHub-repository",
     navigation: "Navigering",
+    opensInNewTab: "Öppnas i en ny flik",
     primary: "Primär",
     sections: "Avsnitt",
     toggleNavigation: "Växla navigering",

package/src/core/ui-packs/th.ts

@@ -41,10 +41,11 @@ export const th: UIStringsOverride = {
   banner: { dismiss: "ปิดประกาศ" },
   changelog: {
     description: "อัปเดตผลิตภัณฑ์และบันทึกประจำรุ่น",
-    showReleases: "แสดงรุ่นของ {version}",
     title: "บันทึกการเปลี่ยนแปลง",
   },
   content: {
+    copyColor: "คัดลอกสี {name} {value}",
+    copyPrompt: "คัดลอกพรอมต์",
     diagramError: "ไม่สามารถแสดงไดอะแกรมนี้ได้",
   },
   feedback: {
@@ -62,6 +63,7 @@ export const th: UIStringsOverride = {
     featured: "แนะนำ",
     githubRepository: "ที่เก็บ GitHub",
     navigation: "การนำทาง",
+    opensInNewTab: "เปิดในแท็บใหม่",
     primary: "หลัก",
     sections: "หมวด",
     toggleNavigation: "สลับการนำทาง",

package/src/core/ui-packs/tr.ts

@@ -42,10 +42,13 @@ export const tr: UIStringsOverride = {
   banner: { dismiss: "Duyuruyu kapat" },
   changelog: {
     description: "Ürün güncellemeleri ve sürüm notları.",
-    showReleases: "{version} sürümlerini göster",
     title: "Değişiklik günlüğü",
   },
-  content: { diagramError: "Bu diyagram görüntülenemedi." },
+  content: {
+    copyColor: "Rengi kopyala: {name} {value}",
+    copyPrompt: "İstemi kopyala",
+    diagramError: "Bu diyagram görüntülenemedi.",
+  },
   feedback: {
     no: "Hayır",
     question: "Bu sayfa yardımcı oldu mu?",
@@ -61,6 +64,7 @@ export const tr: UIStringsOverride = {
     featured: "Öne çıkan",
     githubRepository: "GitHub deposu",
     navigation: "Gezinme",
+    opensInNewTab: "Yeni sekmede açılır",
     primary: "Birincil",
     sections: "Bölümler",
     toggleNavigation: "Gezinmeyi aç/kapat",

package/src/core/ui-packs/uk.ts

@@ -42,10 +42,13 @@ export const uk: UIStringsOverride = {
   banner: { dismiss: "Закрити оголошення" },
   changelog: {
     description: "Оновлення продукту та примітки до випусків.",
-    showReleases: "Показати випуски {version}",
     title: "Журнал змін",
   },
-  content: { diagramError: "Не вдалося відобразити цю діаграму." },
+  content: {
+    copyColor: "Скопіювати колір {name} {value}",
+    copyPrompt: "Скопіювати промпт",
+    diagramError: "Не вдалося відобразити цю діаграму.",
+  },
   feedback: {
     no: "Ні",
     question: "Чи була ця сторінка корисною?",
@@ -61,6 +64,7 @@ export const uk: UIStringsOverride = {
     featured: "Рекомендоване",
     githubRepository: "Репозиторій GitHub",
     navigation: "Навігація",
+    opensInNewTab: "Відкривається в новій вкладці",
     primary: "Основне",
     sections: "Розділи",
     toggleNavigation: "Перемкнути навігацію",

package/src/core/ui-packs/vi.ts

@@ -41,10 +41,11 @@ export const vi: UIStringsOverride = {
   banner: { dismiss: "Đóng thông báo" },
   changelog: {
     description: "Cập nhật sản phẩm và ghi chú phát hành.",
-    showReleases: "Hiện các bản phát hành {version}",
     title: "Nhật ký thay đổi",
   },
   content: {
+    copyColor: "Sao chép màu {name} {value}",
+    copyPrompt: "Sao chép prompt",
     diagramError: "Không thể hiển thị sơ đồ này.",
   },
   feedback: {
@@ -62,6 +63,7 @@ export const vi: UIStringsOverride = {
     featured: "Nổi bật",
     githubRepository: "Kho lưu trữ GitHub",
     navigation: "Điều hướng",
+    opensInNewTab: "Mở trong thẻ mới",
     primary: "Chính",
     sections: "Chuyên mục",
     toggleNavigation: "Chuyển đổi điều hướng",

package/src/core/ui-packs/zh-tw.ts

@@ -41,10 +41,11 @@ export const zhTW: UIStringsOverride = {
   banner: { dismiss: "關閉公告" },
   changelog: {
     description: "產品更新與版本說明。",
-    showReleases: "顯示 {version} 的發布",
     title: "更新日誌",
   },
   content: {
+    copyColor: "複製顏色 {name} {value}",
+    copyPrompt: "複製提示詞",
     diagramError: "無法顯示此圖表。",
   },
   feedback: {
@@ -62,6 +63,7 @@ export const zhTW: UIStringsOverride = {
     featured: "精選",
     githubRepository: "GitHub 儲存庫",
     navigation: "導覽",
+    opensInNewTab: "在新分頁中開啟",
     primary: "主要",
     sections: "章節",
     toggleNavigation: "切換導覽",

package/src/core/ui-packs/zh.ts

@@ -41,10 +41,11 @@ export const zh: UIStringsOverride = {
   banner: { dismiss: "关闭公告" },
   changelog: {
     description: "产品更新与版本说明。",
-    showReleases: "显示 {version} 的发布",
     title: "更新日志",
   },
   content: {
+    copyColor: "复制颜色 {name} {value}",
+    copyPrompt: "复制提示词",
     diagramError: "无法渲染此图表。",
   },
   feedback: {
@@ -62,6 +63,7 @@ export const zh: UIStringsOverride = {
     featured: "精选",
     githubRepository: "GitHub 仓库",
     navigation: "导航",
+    opensInNewTab: "在新标签页中打开",
     primary: "主要",
     sections: "章节",
     toggleNavigation: "切换导航",

package/src/core/unrecognized-keys.ts

@@ -0,0 +1,10 @@
+/**
+ * Zod's own wording for unknown keys no removed-key hint covers, appended to
+ * a hint so an unrelated typo isn't silently dropped from the diagnostic
+ * beside it. Shared by every config object that names a removed field's
+ * replacement (the root config, `ai.ask`, `openapi()`/`asyncapi()`, …).
+ */
+export const unrecognizedKeysMessage = (keys: string[]): string =>
+  `Unrecognized key${keys.length > 1 ? "s" : ""}: ${keys
+    .map((key) => JSON.stringify(key))
+    .join(", ")}`;

package/src/core/version-cut.ts

@@ -11,6 +11,7 @@ import { localizeRoute } from "./i18n.ts";
 import type { BlumeProject } from "./project-graph.ts";
 import { isWithin, scanProject } from "./project-graph.ts";
 import { VERSION_ID } from "./schema.ts";
+import type { Diagnostic } from "./types.ts";
 import { VERSION_LIKE, versionizeRoute } from "./versions.ts";
 
 /** What `cutVersion` did, for the CLI to report. */
@@ -21,6 +22,11 @@ export interface CutResult {
   rewritten: { file: string; count: number }[];
   /** Whether `blume.config.ts` was updated in place. */
   configUpdated: boolean;
+  /**
+   * Whether that update added the whole `versions` block — the first cut of a
+   * project that had no versioning — rather than one `archived` entry.
+   */
+  versionsAdded: boolean;
   /** Ready-to-paste config snippet when in-place update was not possible. */
   configSnippet: string | null;
   /** Absolute path of the created snapshot directory. */
@@ -144,11 +150,17 @@ export const rewriteSnapshotLinks = (
   return { count, text: lines.join("\n") };
 };
 
+/**
+ * The switcher label a first cut gives the live docs. `versions.current.label`
+ * is required, and "Latest" reads right until the author names the release.
+ */
+const CURRENT_LABEL = "Latest";
+
 /** The config entry to add, as a paste-ready snippet for the fallback path. */
 const snippetFor = (id: string, hasVersions: boolean): string =>
   hasVersions
     ? `Add to versions.archived in blume.config.ts (newest first):\n\n  { id: "${id}" },\n`
-    : `Add to blume.config.ts:\n\n  versions: {\n    archived: [{ id: "${id}" }],\n    current: { label: "…" },\n  },\n`;
+    : `Add to blume.config.ts:\n\n  versions: {\n    archived: [{ id: "${id}" }],\n    current: { label: "${CURRENT_LABEL}" },\n  },\n`;
 
 /**
  * Best-effort in-place config update: insert the new id at the head of an
@@ -192,6 +204,101 @@ export const insertArchivedVersion = async (
   return true;
 };
 
+/** The opening brace of the config object: `defineConfig({` or `export default {`. */
+const CONFIG_OBJECT = /(?:defineConfig\(\s*|export\s+default\s+)\{/gu;
+
+/**
+ * Best-effort in-place registration of a first version: add a `versions` block
+ * (the id archived, the live docs labeled {@link CURRENT_LABEL}) as the first
+ * property of the config object. Only the plain shape is edited — exactly one
+ * `defineConfig({` or `export default {` and no `versions` key yet — so a
+ * config built any other way falls back to the printed snippet rather than
+ * risk corrupting it.
+ */
+export const insertVersionsBlock = async (
+  configPath: string,
+  id: string
+): Promise<boolean> => {
+  let text: string;
+  try {
+    text = await readFile(configPath, "utf-8");
+  } catch {
+    return false;
+  }
+  const matches = [...text.matchAll(CONFIG_OBJECT)];
+  const [match] = matches;
+  if (matches.length !== 1 || !match || /\bversions\s*:/u.test(text)) {
+    return false;
+  }
+  const insertAt = match.index + match[0].length;
+  const rest = text.slice(insertAt);
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lineStart = text.lastIndexOf("\n", match.index) + 1;
+  const outer = /^[ \t]*/u.exec(text.slice(lineStart))?.[0] ?? "";
+  // Match the indentation of the property on the next line, when there is one.
+  const indent =
+    /^[ \t]*\r?\n(?<indent>[ \t]*)\S/u.exec(rest)?.groups?.indent ??
+    `${outer}  `;
+  const block = [
+    "versions: {",
+    `  archived: [{ id: "${id}" }],`,
+    `  current: { label: "${CURRENT_LABEL}" },`,
+    "},",
+  ]
+    .map((line) => `${indent}${line}`)
+    .join(eol);
+  const body = rest.trimStart();
+  let tail: string;
+  if (body.startsWith("}")) {
+    // An empty object: close it on its own line.
+    tail = `${eol}${outer}${body}`;
+  } else if (/^[ \t]*\r?\n/u.test(rest)) {
+    tail = rest;
+  } else {
+    // An inline object: move its first property onto the next line.
+    tail = `${eol}${indent}${body}`;
+  }
+  await writeTextAtomic(
+    configPath,
+    `${text.slice(0, insertAt)}${eol}${block}${tail}`
+  );
+  return true;
+};
+
+/**
+ * Version-shaped folders (`v1.0/`) at the top of the content root of a project
+ * with no `versions` config — usually a snapshot `blume version` cut but
+ * couldn't register — which build as ordinary content at `/v1.0/…`, so every
+ * page ships twice. With versioning configured, the scan's own
+ * `BLUME_VERSIONS_UNCONFIGURED_VERSION` covers a folder it doesn't list; this
+ * check is `blume doctor`'s alone, since an unversioned site can have a real
+ * `v1/` section that a warning on every build would only nag about.
+ */
+export const unregisteredSnapshotDiagnostics = (
+  project: BlumeProject
+): Diagnostic[] => {
+  if (project.config.versions) {
+    return [];
+  }
+  const { contentRoot } = project.context;
+  const folders = new Set<string>();
+  for (const page of project.graph.pages) {
+    const [first, ...rest] = page.sourcePath
+      ? relative(contentRoot, page.sourcePath).split("/")
+      : [];
+    if (first && rest.length > 0 && VERSION_LIKE.test(first)) {
+      folders.add(first);
+    }
+  }
+  return [...folders].toSorted().map((folder) => ({
+    code: "BLUME_VERSIONS_UNCONFIGURED_VERSION",
+    file: join(contentRoot, folder),
+    message: `Folder "${folder}/" looks like a version snapshot, but versioning isn't configured, so its pages build as ordinary content at /${folder}/….`,
+    severity: "warning",
+    suggestion: `If it's a snapshot, register it with \`versions: { archived: [{ id: "${folder}" }], current: { label: "${CURRENT_LABEL}" } }\` in blume.config.ts; if it's an ordinary section, ignore this.`,
+  }));
+};
+
 /**
  * Freeze the current docs as an archived version: copy the content tree into
  * `<contentRoot>/<id>/` (excluding existing snapshots), rewrite root-absolute
@@ -304,18 +411,19 @@ export const cutVersion = async (
   };
   await walk(dir);
 
-  const configPath = join(root, "blume.config.ts");
-  const configUpdated =
-    project.config.versions !== undefined &&
-    (await insertArchivedVersion(configPath, id));
+  const configPath =
+    project.context.configFile ?? join(root, "blume.config.ts");
+  const firstVersion = project.config.versions === undefined;
+  const configUpdated = firstVersion
+    ? await insertVersionsBlock(configPath, id)
+    : await insertArchivedVersion(configPath, id);
 
   return {
-    configSnippet: configUpdated
-      ? null
-      : snippetFor(id, project.config.versions !== undefined),
+    configSnippet: configUpdated ? null : snippetFor(id, !firstVersion),
     configUpdated,
     copied,
     dir,
     rewritten,
+    versionsAdded: configUpdated && firstVersion,
   };
 };