blume 1.7.3 → 2.0.1

package/src/markdown/index.ts

@@ -12,6 +12,7 @@ import { codeToHtml } from "shiki";
 import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
+import { externalLinksPlugin } from "./external-links.ts";
 import { MARKDOWN_FEATURES, MDX_FEATURES } from "./features.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
 import { includePlugin } from "./include.ts";
@@ -20,6 +21,7 @@ import { languageIconTransformer } from "./language-icon.ts";
 import { mathPlugin } from "./math.ts";
 import { mermaidPlugin } from "./mermaid.ts";
 import { packageInstallPlugin } from "./package-install.ts";
+import { relativeLinksPlugin } from "./relative-links.ts";
 import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
@@ -87,12 +89,14 @@ const asShikiTransformer = (transformer: { name: string }): ShikiTransformer =>
  * (`[#custom-id]`, `[!toc]`, `[toc]`), which must parse regardless of config —
  * while `markdown.headingAnchors: false` only turns off the self-linking
  * anchor wrap on `<h2>`–`<h6>`. Inline code runs first so the anchor wrap
- * re-refs already-highlighted code.
+ * re-refs already-highlighted code. The external-link plugin is added only
+ * when `markdown.externalLinks` is on, so off stays today's exact output.
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => [
   asHastPlugin(inlineCodeHighlightPlugin(options.codeThemes)),
   asHastPlugin(tableWrapPlugin()),
   asHastPlugin(headingAnchorPlugin({ wrap: options.headingAnchors !== false })),
+  ...(options.externalLinks ? [asHastPlugin(externalLinksPlugin())] : []),
 ];
 
 /**
@@ -196,7 +200,7 @@ export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
   className?: string;
   /**
-   * Light/dark Shiki themes (`markdown.codeBlocks.theme`). Defaults to the same
+   * Light/dark Shiki themes (`markdown.code.theme`). Defaults to the same
    * github pair fenced code uses, so out-of-pipeline code stays in lockstep.
    */
   themes?: CodeThemes;
@@ -248,9 +252,14 @@ export const highlightCode = async (
 export interface BlumeMarkdownOptions {
   /**
    * Light/dark Shiki themes for inline `` `code`{:lang} `` highlighting
-   * (`markdown.codeBlocks.theme`). Defaults to the github pair fenced code uses.
+   * (`markdown.code.theme`). Defaults to the github pair fenced code uses.
    */
   codeThemes?: CodeThemes;
+  /**
+   * Open external links in a new tab, marked with an arrow icon and a
+   * screen-reader hint (`markdown.externalLinks`). Off unless `true`.
+   */
+  externalLinks?: boolean;
   /**
    * Wrap `<h2>`–`<h6>` in self-linking anchors (`markdown.headingAnchors`).
    * On unless explicitly `false`.
@@ -271,25 +280,41 @@ export interface BlumeMarkdownOptions {
   /**
    * The docs content root, bounding `<include>` target resolution (and
    * anchoring `/`-leading include paths). When unset, relative includes still
-   * resolve from the including file.
+   * resolve from the including file. Also the base the `docs` collection's
+   * entry ids are relative to, which relative page links resolve through.
    */
   contentRoot?: string;
+  /**
+   * The `blume:data` snapshot file an ejected app aliases. Relative page links
+   * resolve through the snapshot the CLI publishes; with no CLI in the
+   * process, they read this file instead.
+   */
+  dataFile?: string;
 }
 
 /**
- * MDAST plugins that apply to both `.md` and `.mdx`: the base-path link
- * rewrite (added only when a `basePath` or `deployBase` is configured).
+ * MDAST plugins that apply to both `.md` and `.mdx`: relative page links
+ * rewritten to the root-relative route they mean, then the base-path link
+ * rewrite (added only when a `basePath` or `deployBase` is configured), which
+ * layers `deployment.base` over the rewritten routes.
  */
 const blumeSharedMdastPlugins = (
   options: BlumeMarkdownOptions
-): MdastPlugin[] =>
-  options.basePath || options.deployBase
+): MdastPlugin[] => [
+  asMdastPlugin(
+    relativeLinksPlugin({
+      contentRoot: options.contentRoot,
+      dataFile: options.dataFile,
+    })
+  ),
+  ...(options.basePath || options.deployBase
     ? [
         asMdastPlugin(
           baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "")
         ),
       ]
-    : [];
+    : []),
+];
 
 /**
  * The `<include>` splice. Always first: its mutations apply before the next

package/src/markdown/inline-code.ts

@@ -7,11 +7,14 @@
  * marker and replaces the code's text with Shiki tokens (dual github-light/dark
  * via CSS variables, like fenced blocks).
  *
- * Shiki is imported lazily, so it loads only on pages that actually use inline
+ * Shiki is loaded lazily, so it loads only on pages that actually use inline
  * highlighting — and never when `markdown.code.inline` is off (the plugin is not
  * added to the pipeline at all).
  */
 
+import type * as ShikiModule from "shiki";
+
+import { nodeRequire } from "../core/node-require.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
@@ -77,13 +80,16 @@ type InlineHighlighter = (
   }
 ) => Promise<{ children: HastNode[] }>;
 
-// `import()` caches the module, so this dedupes Shiki across calls on its own.
-const loadHighlighter = async (): Promise<InlineHighlighter> => {
-  const mod = await import("shiki");
+// `require` caches the module, so this dedupes Shiki across calls on its own.
+// Not `import()`: the plugin runs after Astro has closed the module runner an
+// installed Blume's config was evaluated in (see `core/node-require.ts`), so
+// every inline snippet would silently lose its highlighting.
+const loadHighlighter = (): InlineHighlighter => {
+  const { codeToHast }: typeof ShikiModule = nodeRequire("shiki");
   // SAFETY: Shiki accepts arbitrary lang/theme strings at runtime (an unknown
   // one rejects the promise, which the caller catches); only its bundled types
   // constrain them to known ids, so the loose signature narrows nothing real.
-  return mod.codeToHast as InlineHighlighter;
+  return codeToHast as InlineHighlighter;
 };
 
 /** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */
@@ -102,7 +108,7 @@ export const inlineCodeHighlightPlugin = (
         return;
       }
       try {
-        const codeToHast = await loadHighlighter();
+        const codeToHast = loadHighlighter();
         const root = await codeToHast(parsed.code, {
           defaultColor: false,
           lang: parsed.lang,

package/src/markdown/relative-links.ts

@@ -0,0 +1,324 @@
+import { readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { dirname, normalize, relative, resolve } from "pathe";
+
+import { readRuntimeModule } from "../astro/runtime-modules.ts";
+import { isIndexFileName, resolveRelativeHref } from "../core/links.ts";
+import type { RelativeLinkBase } from "../core/links.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+interface UrlNode extends MdastNode {
+  url?: string | null;
+}
+
+/** An MDX JSX attribute, as the plugin reads it. */
+interface JsxAttribute {
+  [key: string]: MdastValue;
+  name?: string;
+  type?: string;
+  value?: MdastValue;
+}
+
+/** An MDX JSX element (`<Card href="./install" />`), as the plugin reads it. */
+interface JsxNode extends MdastNode {
+  attributes?: JsxAttribute[];
+  children?: MdastValue[];
+  name?: string | null;
+}
+
+/** The visitor-context slice this plugin uses (see `mdast.ts` for the model). */
+interface RelativeLinksContext {
+  fileURL: URL | undefined;
+  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
+  setProperty: (node: MdastNode, key: "url", value: string) => void;
+}
+
+/** The slice of the `blume:data` snapshot the plugin reads. */
+interface RouteData {
+  config: {
+    i18n?: { defaultLocale: string; locales: { code: string }[] } | null;
+  };
+  routes: {
+    collection: string;
+    entryId: string;
+    fallback: boolean;
+    locale: string;
+    path: string;
+  }[];
+}
+
+/** What the plugin knows about where content files publish. */
+interface RouteIndex {
+  /** `collection` + NUL + `entryId` → the route that entry publishes at. */
+  routes: Map<string, string>;
+  /** Every route the site serves, fallback copies included. */
+  paths: Set<string>;
+  /** Tokens an index file name may carry before its extension. */
+  localeTokens: string[];
+  /** The locale folders beside the default tree (every locale but the default). */
+  localeFolders: string[];
+}
+
+/** A content file, located: its page, and how to find the files beside it. */
+interface LocatedPage extends RelativeLinkBase {
+  /** The route a sibling file publishes at, from its path relative to `file`. */
+  routeOf: (path: string) => string | undefined;
+  /** Every route the site serves, for dotted page names (`./node.js`). */
+  routes: ReadonlySet<string>;
+}
+
+/** A JSX component name (`Card`, `Tree.File`), as opposed to an HTML tag. */
+const COMPONENT_NAME = /^[A-Z]/u;
+
+/** A plain string attribute value; an expression value isn't a link target. */
+const isStringValue = (value: MdastValue): value is string =>
+  typeof value === "string";
+
+const entryKey = (collection: string, entryId: string): string =>
+  `${collection}\0${entryId}`;
+
+/**
+ * Index the snapshot's routes by collection entry. A file shared by every
+ * locale publishes once per locale; the default locale's route stands for it,
+ * and the rendered link moves into the reader's locale afterwards (see
+ * `LocaleLinks.astro`). Fallback copies render another locale's file, so they
+ * never stand for it.
+ */
+const indexRoutes = (data: RouteData): RouteIndex => {
+  const defaultLocale = data.config.i18n?.defaultLocale;
+  const routes = new Map<string, string>();
+  for (const route of data.routes) {
+    if (route.fallback) {
+      continue;
+    }
+    const key = entryKey(route.collection, route.entryId);
+    if (!routes.has(key) || route.locale === defaultLocale) {
+      routes.set(key, route.path);
+    }
+  }
+  const locales = data.config.i18n?.locales.map((locale) => locale.code) ?? [];
+  return {
+    localeFolders: locales.filter((code) => code !== defaultLocale),
+    localeTokens: data.config.i18n ? ["$", ...locales] : [],
+    paths: new Set(data.routes.map((route) => route.path)),
+    routes,
+  };
+};
+
+/**
+ * The same entry path in the default tree: a page in a locale folder that
+ * links a sibling not translated yet (`fr/guides/setup.mdx` missing) means
+ * the default tree's file (`guides/setup.mdx`), whose route — its own `slug`
+ * included — moves into the reader's locale afterwards, onto the fallback
+ * copy (see `LocaleLinks.astro`).
+ */
+const defaultTreePath = (
+  entryId: string,
+  localeFolders: readonly string[]
+): string | undefined => {
+  const slash = entryId.indexOf("/");
+  return slash !== -1 && localeFolders.includes(entryId.slice(0, slash))
+    ? entryId.slice(slash + 1)
+    : undefined;
+};
+
+export interface RelativeLinksPluginOptions {
+  /** The `docs` collection's base directory, which entry ids are relative to. */
+  contentRoot?: string;
+  /**
+   * The `blume:data` JSON file, for an ejected app: with no CLI in the process
+   * to publish the snapshot, the plugin reads the file eject writes instead.
+   */
+  dataFile?: string;
+}
+
+/**
+ * Satteri MDAST plugin that rewrites relative page links (`[Install](./install)`,
+ * `[Setup](../guides/setup.md)`) to the root-relative route they mean, using
+ * the same file-style reading `blume validate` checks them against
+ * (`resolveRelativeHref`). Left as written, the browser resolves them against
+ * the page's slashless URL — so `./install` on an index page (`/guides`) lands
+ * on `/install`, and a `.md` link opens the raw Markdown source instead of the
+ * page. The page's own route, and a linked file's, come from the `blume:data`
+ * snapshot the CLI publishes (or, ejected, the file eject writes), keyed by
+ * collection entry: `docs` entries by their path under `contentRoot`, staged
+ * entries (remote sources) by the longest trailing path that names one. A file
+ * the snapshot doesn't know keeps its links as written.
+ *
+ * Runs before the base-links plugin, whose `basePath` layering is idempotent,
+ * so a rewritten route (which already carries `basePath`) only gains the
+ * `deployment.base` prefix.
+ */
+export const relativeLinksPlugin = (
+  options: RelativeLinksPluginOptions = {}
+) => {
+  const contentRoot = options.contentRoot
+    ? resolve(options.contentRoot)
+    : undefined;
+  const dataFile = options.dataFile ? resolve(options.dataFile) : undefined;
+
+  // Parsed once per published snapshot: the CLI republishes on regeneration,
+  // and an unchanged snapshot is the same string, so every page compiled
+  // between regenerations reuses one index.
+  let cached: { index: RouteIndex; text: string } | undefined;
+  let fileStamp: number | undefined;
+  let fileText: string | undefined;
+
+  /** The ejected snapshot file's text, re-read only when it changes. */
+  const readDataFile = (path: string): string | undefined => {
+    let stamp: number;
+    try {
+      stamp = statSync(path).mtimeMs;
+    } catch {
+      return undefined;
+    }
+    if (stamp !== fileStamp) {
+      fileStamp = stamp;
+      fileText = readFileSync(path, "utf-8");
+    }
+    return fileText;
+  };
+
+  const routeIndex = (): RouteIndex | undefined => {
+    const text =
+      readRuntimeModule("blume:data") ??
+      (dataFile ? readDataFile(dataFile) : undefined);
+    if (text === undefined) {
+      return undefined;
+    }
+    if (cached?.text !== text) {
+      const data: RouteData = JSON.parse(text);
+      cached = { index: indexRoutes(data), text };
+    }
+    return cached.index;
+  };
+
+  /** The page `file` renders, with a resolver for the files beside it. */
+  const locate = (file: string, index: RouteIndex): LocatedPage | undefined => {
+    const locateIn = (
+      collection: string,
+      base: string
+    ): LocatedPage | undefined => {
+      const entryId = relative(base, file);
+      const route = index.routes.get(entryKey(collection, entryId));
+      if (route === undefined) {
+        return undefined;
+      }
+      return {
+        isIndex: isIndexFileName(entryId, index.localeTokens),
+        route,
+        routeOf: (path) => {
+          const target = relative(base, resolve(dirname(file), path));
+          const inDefaultTree = defaultTreePath(target, index.localeFolders);
+          return (
+            index.routes.get(entryKey(collection, target)) ??
+            (inDefaultTree === undefined
+              ? undefined
+              : index.routes.get(entryKey(collection, inDefaultTree)))
+          );
+        },
+        routes: index.paths,
+      };
+    };
+    if (contentRoot && !relative(contentRoot, file).startsWith("../")) {
+      return locateIn("docs", contentRoot);
+    }
+    // A staged entry's id is its path under the staging dir, which the plugin
+    // isn't told: the longest trailing path naming a staged entry wins.
+    const segments = file.split("/");
+    for (let start = 1; start < segments.length; start += 1) {
+      const staged = locateIn(
+        "staged",
+        segments.slice(0, start).join("/") || "/"
+      );
+      if (staged) {
+        return staged;
+      }
+    }
+    return undefined;
+  };
+
+  /** The route `url` means on the page at `fileURL`, when it's relative. */
+  const resolveUrl = (
+    url: string,
+    fileURL: URL | undefined
+  ): string | undefined => {
+    // Cheap first: a target that can't be relative never needs the index. A
+    // dotted name (`./node.js`) passes, since only the index knows its route.
+    if (
+      !fileURL ||
+      resolveRelativeHref(
+        url,
+        { isIndex: false, route: "/" },
+        undefined,
+        () => true
+      ) === undefined
+    ) {
+      return undefined;
+    }
+    const index = routeIndex();
+    const page = index && locate(normalize(fileURLToPath(fileURL)), index);
+    if (!page) {
+      return undefined;
+    }
+    const next = resolveRelativeHref(url, page, page.routeOf, (route) =>
+      page.routes.has(route)
+    );
+    return next === url ? undefined : next;
+  };
+
+  const rewrite = (node: UrlNode, ctx: RelativeLinksContext): void => {
+    const { url } = node;
+    const next = isStringValue(url) ? resolveUrl(url, ctx.fileURL) : undefined;
+    if (next !== undefined) {
+      ctx.setProperty(node, "url", next);
+    }
+  };
+
+  // A component's string `href` (`<Card href="./install">`) is the same kind
+  // of link, and `blume validate` reads it as one. Lowercase elements are
+  // raw HTML in a `.md` page, which neither rewrites nor checks, so only
+  // components are rewritten; an expression-valued `href={…}` is left alone.
+  const rewriteHref = (node: JsxNode, ctx: RelativeLinksContext): void => {
+    if (!node.name || !COMPONENT_NAME.test(node.name)) {
+      return;
+    }
+    const attributes = node.attributes ?? [];
+    const at = attributes.findIndex(
+      (attribute) =>
+        attribute.type === "mdxJsxAttribute" &&
+        attribute.name === "href" &&
+        isStringValue(attribute.value)
+    );
+    const value = attributes[at]?.value;
+    const next = isStringValue(value)
+      ? resolveUrl(value, ctx.fileURL)
+      : undefined;
+    if (next !== undefined) {
+      // Sätteri can't set a JSX element's attributes in place, so the element
+      // is swapped for a copy; its children carry over and are still visited.
+      ctx.replaceNode(node, {
+        attributes: attributes.map((attribute, position) =>
+          position === at
+            ? { name: attribute.name, type: attribute.type, value: next }
+            : attribute
+        ),
+        children: node.children ?? [],
+        name: node.name,
+        type: node.type,
+      });
+    }
+  };
+
+  // `link` covers inline links; `definition` covers reference-style
+  // definitions (`[x]: ./install`). Images stay with the image pipeline, which
+  // resolves relative embeds from beside the page source.
+  return {
+    definition: rewrite,
+    link: rewrite,
+    mdxJsxFlowElement: rewriteHref,
+    mdxJsxTextElement: rewriteHref,
+    name: "blume-relative-links",
+  };
+};

package/src/markdown/themes.ts

@@ -2,7 +2,7 @@
  * The light/dark Shiki themes Blume highlights code with. Every Shiki surface —
  * fenced code (the generated Astro `shikiConfig.themes`), inline `` `code`{:lang} ``,
  * out-of-pipeline `highlightCode`, and `<Diff>` — resolves to the same pair so a
- * project's `markdown.codeBlocks.theme` shifts them all in lockstep. This is the
+ * project's `markdown.code.theme` shifts them all in lockstep. This is the
  * single home for the github fallback used when nothing is configured.
  */
 
@@ -12,7 +12,7 @@ import type { ThemeRegistrationAny } from "shiki";
 export type CodeTheme = string | ThemeRegistrationAny;
 
 /**
- * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * A light/dark Shiki theme pair (`markdown.code.theme`). A `type` (not an
  * `interface`) so it keeps the implicit index signature Shiki's `themes`
  * parameter (`Partial<Record<string, …>>`) expects.
  */
@@ -22,7 +22,7 @@ export type CodeThemes = {
   light: CodeTheme;
 };
 
-/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+/** The default pair, used when `markdown.code.theme` is unset. */
 export const DEFAULT_CODE_THEMES: CodeThemes = {
   dark: "github-dark",
   light: "github-light",

package/src/migrate/migrate.ts

@@ -0,0 +1,149 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+/**
+ * `blume migrate`'s logic, kept out of the command module so it runs (and is
+ * covered) in-process. Migration is judgment work — idiomatic navigation,
+ * component rewrites, what to drop — so it stays in the `blume-migrate` skill,
+ * shipped inside the package; this module only names the source (from the
+ * argument, or detected from the repo's own files) and writes the prompt that
+ * points a coding agent at the skill and that source's mappings.
+ */
+
+/** The docs frameworks the skill has a mapping reference for. */
+export const MIGRATE_SOURCES = [
+  "mintlify",
+  "fumadocs",
+  "docusaurus",
+  "starlight",
+  "nextra",
+] as const;
+
+export type MigrateSourceId = (typeof MIGRATE_SOURCES)[number];
+
+/** Display names, for messages and the prompt. */
+export const MIGRATE_SOURCE_NAMES: Record<MigrateSourceId, string> = {
+  docusaurus: "Docusaurus",
+  fumadocs: "Fumadocs",
+  mintlify: "Mintlify",
+  nextra: "Nextra",
+  starlight: "Starlight",
+};
+
+/** The skill's directory inside the published package. */
+export const MIGRATE_SKILL_DIR = join("skills", "blume-migrate");
+
+export const isMigrateSource = (value: string): value is MigrateSourceId =>
+  MIGRATE_SOURCES.some((source) => source === value);
+
+/** A detected source and the file or dependency that gave it away. */
+export interface DetectedSource {
+  evidence: string;
+  source: MigrateSourceId;
+}
+
+/** The slice of `package.json` detection reads. */
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+/** Every dependency the project's `package.json` names, or none when unreadable. */
+const dependencyNames = async (root: string): Promise<Set<string>> => {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) {
+    return new Set();
+  }
+  try {
+    // SAFETY: package.json is a JSON object; only its dependency maps are read.
+    const pkg = JSON.parse(await readFile(path, "utf-8")) as PackageJson;
+    return new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+  } catch {
+    // A malformed package.json is the agent's to deal with; detection just
+    // falls back to the other signals.
+    return new Set();
+  }
+};
+
+/**
+ * Each source's tell, in the order the skill's workflow checks them: a config
+ * file the framework owns, or a dependency only it installs.
+ */
+const SIGNALS: {
+  deps?: string[];
+  files?: string[];
+  source: MigrateSourceId;
+}[] = [
+  { files: ["docs.json", "mint.json"], source: "mintlify" },
+  {
+    files: [
+      "docusaurus.config.ts",
+      "docusaurus.config.js",
+      "docusaurus.config.mjs",
+      "docusaurus.config.cjs",
+    ],
+    source: "docusaurus",
+  },
+  {
+    deps: ["fumadocs-core", "fumadocs-ui", "fumadocs-mdx"],
+    files: ["source.config.ts"],
+    source: "fumadocs",
+  },
+  { deps: ["nextra"], source: "nextra" },
+  { deps: ["@astrojs/starlight"], source: "starlight" },
+];
+
+/**
+ * Detect the docs framework a project is built on from its own files, or
+ * null when nothing gives it away (the skill still migrates any framework,
+ * working from its general model instead of a mapping reference).
+ */
+export const detectMigrateSource = async (
+  root: string
+): Promise<DetectedSource | null> => {
+  const deps = await dependencyNames(root);
+  for (const { deps: tells = [], files = [], source } of SIGNALS) {
+    const file = files.find((name) => existsSync(join(root, name)));
+    if (file) {
+      return { evidence: file, source };
+    }
+    const dep = tells.find((name) => deps.has(name));
+    if (dep) {
+      return { evidence: `${dep} in package.json`, source };
+    }
+  }
+  return null;
+};
+
+/**
+ * The handoff prompt: follow the skill, where its mappings for this source
+ * are, and the few rules worth restating — the target version, and that no
+ * page or URL is lost.
+ */
+export const migratePrompt = (options: {
+  detected: DetectedSource | null;
+  skillDir: string;
+  source: MigrateSourceId | null;
+  version: string;
+}): string => {
+  const { detected, skillDir, source, version } = options;
+  const evidence =
+    detected && detected.source === source
+      ? ` (detected from ${detected.evidence})`
+      : "";
+  const sourceLine = source
+    ? `The source is ${MIGRATE_SOURCE_NAMES[source]}${evidence}. Its exact mappings are in ${join(skillDir, "references", `${source}.md`)}.`
+    : `The source framework wasn't detected, so inventory the repo first. If it's ${MIGRATE_SOURCES.map((id) => MIGRATE_SOURCE_NAMES[id]).join(", ")}, read that framework's file in ${join(skillDir, "references")}; otherwise follow the skill's mental model directly.`;
+  return `Migrate this documentation project to Blume ${version}.
+
+Follow the blume-migrate skill: read ${join(skillDir, "SKILL.md")} first and work through its migration workflow. Wherever the skill says \`<skill>\`, it means ${skillDir}.
+
+${sourceLine}
+
+Add \`blume@^${version}\` as the docs package's dependency. Keep every page, and add a redirect for any URL that moves. Report everything you drop or approximate, and run the skill's verification steps before you finish.`;
+};