@anja.codes/vitakit 0.2.0 → 0.3.0

package/dist/shared/{vitakit.CoWX2Z4R.mjs → vitakit.zwr1ssO5.mjs}

@@ -94,7 +94,8 @@ function commandHelp(spec, run) {
     "Usage",
     ...(spec.usage ? spec.usage(run) : [usageLine(spec, run)]).map((line) => `  ${line}`),
     "",
-    spec.help(run).trim(),
+    // Only blank lines: help that starts with an indented example keeps its indent.
+    spec.help(run).replace(/^\s*\n/, "").trimEnd(),
     "",
     "Options",
     ...rows.map(([flag, description]) => `  ${flag.padEnd(width)}  ${description}`),
@@ -251,6 +252,8 @@ ${after.join("\n")}` : ""}
 const SECTION_OPTIONS = ["page", "document", "title", "after", "like"];
 const FIELD_OPTIONS = ["type", "several", "required", "choice"];
 const PAGE_OPTIONS = ["title", "no-menu"];
+const SELECTION_OPTIONS = ["where", "since", "until", "sort", "order", "group-by", "limit"];
+const LIST_OPTIONS = ["page", "document", "title", "after", ...SELECTION_OPTIONS];
 const COMMON = ["help", "root", "no-color", "dry-run", "yes"];
 function onlyOptions(kind, values, allowed) {
   const wrong = Object.keys(values).filter((name) => values[name] !== void 0 && ![...COMMON, ...allowed].includes(name));
@@ -291,7 +294,7 @@ async function addSection(context, id, values) {
   const { sectionNameProblem } = await import('../chunks/sections.mjs');
   const problem = sectionNameProblem(id);
   if (problem) throw new CommandError(problem);
-  if (id === "publications") throw new CommandError("publications come from content/publications.bib; `vitakit customize publications` changes their groups");
+  if (id === "publications") throw new CommandError(`publications come from content/publications.bib; to show some of them, \`${run.bin("vitakit", "add publication-list <name>")}\` declares a list`);
   const { inventory } = await import('../chunks/inventory.mjs');
   const { Workspace } = await import('../chunks/plan.mjs');
   const authoring = await import('../chunks/authoring.mjs');
@@ -468,6 +471,138 @@ async function addField(context, id, name, values) {
   ];
   return finish(context, ws, values, { before, after });
 }
+function listSettings(values) {
+  const number = (name) => {
+    if (values[name] === void 0) return void 0;
+    const value = Number(values[name]);
+    if (!Number.isInteger(value)) throw new UsageError(`--${name} must be a whole number`, "add");
+    return value;
+  };
+  const where = {};
+  for (const expression of strings$1(values.where)) {
+    const equals = expression.indexOf("=");
+    const field = expression.slice(0, equals).trim();
+    const value = expression.slice(equals + 1).trim();
+    if (equals === -1 || !field || !value) throw new UsageError(`--where ${expression}: use field=value, e.g. status=preprint`, "add");
+    const current = where[field];
+    where[field] = current === void 0 ? value : [current].flat().concat(value);
+  }
+  return {
+    ...Object.keys(where).length ? { where } : {},
+    since: number("since"),
+    until: number("until"),
+    sort: values.sort,
+    order: values.order,
+    limit: number("limit"),
+    groupBy: values["group-by"]
+  };
+}
+async function askListSettings(context, statuses) {
+  const prompt = await import('../chunks/prompt.mjs');
+  const { io } = context;
+  const settings = {};
+  if (await prompt.choose(io, "Which publications?", [{ label: "all of them", value: false }, { label: "only some statuses", value: true }])) {
+    const answer = await prompt.input(io, `Which, separated by commas (${statuses.join(", ")})`);
+    const chosen = answer.split(",").map((status) => status.trim()).filter(Boolean);
+    if (chosen.length) settings.where = { status: chosen.length === 1 ? chosen[0] : chosen };
+  }
+  const limit = await prompt.input(io, "How many at most? (Enter for all)");
+  if (limit) settings.limit = Number(limit);
+  const order = await prompt.choose(io, "In what order?", [
+    { label: "newest first", value: {} },
+    { label: "oldest first", value: { order: "asc" } },
+    { label: "by title", value: { sort: "title" } },
+    { label: "as in publications.bib", value: { sort: "source" } }
+  ]);
+  Object.assign(settings, order);
+  const groupBy = await prompt.choose(io, "In groups, each with a heading?", [
+    { label: "no, one list", value: void 0 },
+    { label: "by status (Published, Preprints, \u2026)", value: "status" },
+    { label: "by year", value: "year" }
+  ]);
+  if (groupBy) settings.groupBy = groupBy;
+  return settings;
+}
+async function addPublicationList(context, name, values) {
+  const { io, run, root } = context;
+  const { inventory } = await import('../chunks/inventory.mjs');
+  const { Workspace } = await import('../chunks/plan.mjs');
+  const { loadPublicationsSchema } = await import('../chunks/bibliography.mjs').then(function (n) { return n.e; });
+  const { LISTS_FILE, LISTS_HEADER, resolveList } = await import('../chunks/publication-lists.mjs');
+  const { addPublicationList: addToFile, publicationListLine } = await import('../chunks/yaml.mjs');
+  const authoring = await import('../chunks/authoring.mjs');
+  const prompt = await import('../chunks/prompt.mjs');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new CommandError(`"${name}" must be lowercase kebab-case, e.g. recent-papers`);
+  const inv = await inventory(root);
+  const ws = new Workspace(root);
+  const interactive = asking(context, values);
+  const selecting = SELECTION_OPTIONS.some((option) => values[option] !== void 0);
+  const notes = [];
+  const source = await ws.read(LISTS_FILE) ?? "";
+  const line = publicationListLine(source, name);
+  const exists = line !== void 0;
+  if (exists) {
+    if (selecting) throw new CommandError(`${LISTS_FILE}:${line} declares ${name} already; change its settings there. Without selection options, this command only shows it somewhere else.`);
+    ws.keep(LISTS_FILE, `the list ${name}, as it is`);
+  } else {
+    const schema = await loadPublicationsSchema(root);
+    const settings = selecting || !interactive ? listSettings(values) : await askListSettings(context, schema.statuses.map((status) => status.id));
+    const { readBibliography } = await import('../chunks/bibliography.mjs').then(function (n) { return n.e; });
+    const { selectPublications } = await import('../chunks/publication-lists.mjs');
+    let empty;
+    try {
+      const list = resolveList(name, Object.fromEntries(Object.entries(settings).filter(([, value]) => value !== void 0)), schema);
+      empty = !selectPublications(await readBibliography(join(root, "content", "publications.bib"), schema), name, list, schema).length;
+    } catch (error) {
+      throw new CommandError(error instanceof Error ? error.message : String(error));
+    }
+    if (empty) notes.push(`No publication matches ${name} yet, so it shows nothing for now; check its settings if that is a surprise.`);
+    const result = addToFile(source || LISTS_HEADER, name, settings);
+    if (!result.ok) throw new CommandError(`${LISTS_FILE} ${result.reason}`);
+    if (source) await ws.edit(LISTS_FILE, result.value, `declares the list ${name}`);
+    else ws.create(LISTS_FILE, result.value, `declares the list ${name}`, { show: true });
+  }
+  const after = values.after;
+  const pages = strings$1(values.page).map((route) => route.endsWith("/") ? route : `${route}/`);
+  const documents = strings$1(values.document);
+  let title = values.title;
+  if (interactive && !pages.length && !documents.length) {
+    const shownOn = new Set(inv.web.publications.filter((placement) => placement.list === name).map((placement) => placement.route));
+    const choices = [
+      ...inv.pages.filter((page) => page.vue && !shownOn.has(page.route)).map((page) => ({ label: `${page.route}  (${page.vue})`, value: page.route })),
+      { label: "not on the website, for now", value: "" }
+    ];
+    const route = await prompt.choose(io, `Show ${name} on which page of your website?`, choices, Math.max(0, choices.findIndex((choice) => choice.value === "/publications/")));
+    if (route) pages.push(route);
+    for (const document of inv.documents.filter((candidate) => !candidate.publications.some((placement) => placement.list === name))) {
+      if (await prompt.confirm(io, `
+Include ${name} in the PDF ${document.tex}?`, false)) documents.push(document.name);
+    }
+    if ((pages.length || documents.length) && title === void 0) title = await prompt.input(io, "\nHeading", prompt.headingFor(name));
+  }
+  title ??= prompt.headingFor(name);
+  for (const route of pages) {
+    const path = inv.pages.find((page) => page.route === route)?.vue;
+    if (!path) throw new CommandError(`--page ${route}: no Vue page has this route; \`${run.bin("vitakit", "add page <name>")}\` creates one`);
+    await authoring.planListOnPage(ws, inv, path, { list: name, ...title ? { title } : {}, ...after ? { after } : {} });
+  }
+  for (const document of documents) {
+    if (!inv.documents.some((candidate) => candidate.name === document)) {
+      throw new CommandError(`--document ${document}: no cv-tex/${document}.tex; the documents are ${inv.documents.map((candidate) => candidate.name).join(", ") || "(none)"}`);
+    }
+    await authoring.planListInDocument(ws, document, { id: name, ...title ? { title } : {}, ...after ? { after } : {} });
+  }
+  if (!pages.length && !documents.length && !exists) {
+    notes.push(`Not shown anywhere yet: \`${run.bin("vitakit", `add publication-list ${name} --page /publications/`)}\` or \`--document cv\` adds it later.`);
+  }
+  return finish(context, ws, values, {
+    before: notes,
+    after: [
+      `Which publications the list ${name} shows is set in ${LISTS_FILE}.`,
+      `\`${run.bin("vitakit", `explain ${name}`)}\` shows which ones it contains, and why.`
+    ]
+  });
+}
 async function addPage(context, name, values) {
   const { io, run, root } = context;
   const { inventory } = await import('../chunks/inventory.mjs');
@@ -490,13 +625,20 @@ async function addPage(context, name, values) {
 }
 const add = {
   name: "add",
-  summary: "add a section, a field of a section, or a website page",
+  summary: "add a section, a field of a section, a website page, or a publication list",
   positionals: [{ name: "what", required: true }, { name: "name" }, { name: "field" }],
   options: {
-    "page": { type: "string", multiple: true, value: "<route>", description: "section: show it on this page, e.g. /cv/ (repeatable)" },
-    "document": { type: "string", multiple: true, value: "<name>", description: "section: include it in this PDF document, e.g. cv (repeatable)" },
-    "after": { type: "string", value: "<section>", description: "section: place it after this section" },
-    "title": { type: "string", value: "<text>", description: "section: its heading; page: its title" },
+    "page": { type: "string", multiple: true, value: "<route>", description: "section, publication-list: show it on this page, e.g. /cv/ (repeatable)" },
+    "document": { type: "string", multiple: true, value: "<name>", description: "section, publication-list: include it in this PDF document, e.g. cv (repeatable)" },
+    "after": { type: "string", value: "<name>", description: "section, publication-list: place it after this section or list" },
+    "title": { type: "string", value: "<text>", description: "section, publication-list: its heading; page: its title" },
+    "where": { type: "string", multiple: true, value: "<field=value>", description: "publication-list: only entries with this value, e.g. status=preprint (repeatable)" },
+    "since": { type: "string", value: "<year>", description: "publication-list: only entries from this year on" },
+    "until": { type: "string", value: "<year>", description: "publication-list: only entries up to this year" },
+    "sort": { type: "string", value: "<by>", description: "publication-list: date (default), year, title, source or a field" },
+    "order": { type: "string", value: "<asc|desc>", description: "publication-list: sort direction" },
+    "group-by": { type: "string", value: "<by>", description: "publication-list: status, year or a field" },
+    "limit": { type: "string", value: "<count>", description: "publication-list: at most this many" },
     "like": { type: "string", value: "<section>", description: "section: use the schema of another section" },
     "type": { type: "string", value: "<type>", description: "field: text, formatted-text, number, yes-no, date, web-address, link or choice" },
     "several": { type: "boolean", description: "field: an entry may have a list of values" },
@@ -510,7 +652,8 @@ const add = {
   usage: (run) => [
     run.bin("vitakit", "add section <name> [options]"),
     run.bin("vitakit", "add field <section> <name> [options]"),
-    run.bin("vitakit", "add page <name> [options]")
+    run.bin("vitakit", "add page <name> [options]"),
+    run.bin("vitakit", "add publication-list <name> [options]")
   ],
   help: (run) => `
 A section is a file content/<name>.yml. \`add section\` creates what is missing:
@@ -533,10 +676,24 @@ content/pages/<name>.md, and adds it to the menu:
 
   ${run.bin("vitakit", "add page talks --title Talks")}
 
+\`add publication-list\` declares which publications a list shows, in
+content/publication-lists.yml, and shows it on a page or in a PDF:
+
+  ${run.bin("vitakit", "add publication-list preprints --where status=preprint --page /publications/")}
+  ${run.bin("vitakit", 'add publication-list recent --limit 5 --document cv --title "Recent publications"')}
+
+For a list that exists already, it only adds it to more pages and PDFs.
+
 Everything is shown before it is written, and asked; nothing existing is
 replaced. A file that cannot be changed safely gets a line to paste instead.`,
   async run(context, { positionals, values }) {
     const [what, name, field] = positionals;
+    if (what === "publication-list") {
+      if (!name) throw new UsageError("missing <name>: `add publication-list <name>`", "add");
+      if (field !== void 0) throw new UsageError(`unexpected argument "${field}"`, "add");
+      onlyOptions(what, values, LIST_OPTIONS);
+      return addPublicationList(context, name, values);
+    }
     if (what === "section" || what === "page") {
       if (!name) throw new UsageError(`missing <name>: \`add ${what} <name>\``, "add");
       if (field !== void 0) throw new UsageError(`unexpected argument "${field}"`, "add");
@@ -548,7 +705,7 @@ replaced. A file that cannot be changed safely gets a line to paste instead.`,
       onlyOptions(what, values, FIELD_OPTIONS);
       return addField(context, name, field, values);
     }
-    throw new UsageError(`add what? \`add section <name>\`, \`add field <section> <name>\` or \`add page <name>\`${what ? `, not "${what}"` : ""}`, "add");
+    throw new UsageError(`add what? \`add section <name>\`, \`add field <section> <name>\`, \`add page <name>\` or \`add publication-list <name>\`${what ? `, not "${what}"` : ""}`, "add");
   }
 };
 
@@ -562,12 +719,12 @@ async function planSchema(context, ws, inv, id, values, notes) {
   const path = `schemas/${id}.ts`;
   if (id === "publications") {
     if (ws.exists(path)) {
-      notes.after.push(`${path} is yours already: its groups, badges and fields decide how content/publications.bib is grouped and linked.`);
+      notes.after.push(`${path} is yours already: its statuses, badges and fields decide what publications can be and how they are linked. Which ones a list shows is set in content/publication-lists.yml.`);
       return;
     }
-    ws.create(path, await builtinSchemaSource("publications"), "vitakit's publication groups, badges and fields, to change");
+    ws.create(path, await builtinSchemaSource("publications"), "vitakit's publication statuses, badges and fields, to change");
     notes.before.push("The website, `vitakit verify` and the PDF all read it from now on.");
-    notes.after.push(`Edit ${path}: change groups, add badges, pass on BibTeX fields. Check it: \`${run.bin("vitakit", "validate")}\``);
+    notes.after.push(`Edit ${path}: change statuses, add badges, pass on BibTeX fields. Check it: \`${run.bin("vitakit", "validate")}\``);
     return;
   }
   const section = inv.sections.find((candidate) => candidate.id === id);
@@ -596,7 +753,7 @@ async function planSchema(context, ws, inv, id, values, notes) {
 async function planWeb(context, ws, inv, section, fields, list, values, notes) {
   const { io, run } = context;
   const { entryComponent, listComponent } = await import('../chunks/snippets.mjs');
-  const { useComponentForSection } = await import('../chunks/vue.mjs').then(function (n) { return n.v; });
+  const { useComponentForSection } = await import('../chunks/vue.mjs');
   const { planPlaceOnPage } = await import('../chunks/authoring.mjs');
   const prompt = await import('../chunks/prompt.mjs');
   const id = section.id;
@@ -737,10 +894,12 @@ ${copied}`;
   }
   if (ws.exists(path)) ws.replace(path, source, `${reason}; yours is kept next to it as a .backup`, { show: true });
   else ws.create(path, source, reason, { show: true });
-  const included = inv.documents.filter((document) => document.placements.some((placement) => placement.section === id));
-  if (!included.length) notes.before.push(`No PDF document includes ${id} yet: \`${run.bin("vitakit", `add section ${id} --document ${inv.documents[0].name}`)}\``);
+  const included = inv.documents.filter((document) => id === "publications" ? document.publications.length : document.placements.some((placement) => placement.section === id));
+  if (!included.length) {
+    notes.before.push(id === "publications" ? `No PDF document shows a publication list yet: add \\vitapublications[Publications]{all} to ${inv.documents[0].tex}` : `No PDF document includes ${id} yet: \`${run.bin("vitakit", `add section ${id} --document ${inv.documents[0].name}`)}\``);
+  }
   if (id === "publications") {
-    notes.before.push("This template groups the references; how each one is formatted is up to biblatex, in cv-tex/preamble.tex.");
+    notes.before.push("This template prints a publication list, group by group; how each reference is formatted is up to biblatex, in cv-tex/preamble.tex.");
   }
   notes.after.push(`Edit ${path}; \`${run.bin("vitakit", `validate ${id}`)}\` checks it without LaTeX, \`${run.bin("vitakit", "pdf")}\` builds.`);
 }
@@ -937,6 +1096,12 @@ function pdfCell(inventory, section) {
   const documents = [...new Set(pdfPlacementsOf(inventory, section).map((placement) => placement.document))];
   return documents.length ? documents.join(", ") : "\u2013";
 }
+function listPlacementsText(inventory, list) {
+  const pages = inventory.web.publications.filter((placement) => placement.list === list).map((placement) => placement.route ?? placement.file);
+  const documents = inventory.documents.filter((document) => document.publications.some((placement) => placement.list === list)).map((document) => `${document.name} (pdf)`);
+  const all = [.../* @__PURE__ */ new Set([...pages, ...documents])];
+  return all.length ? all.join(", ") : "not shown anywhere";
+}
 function readableIssue(line) {
   return line.replace(/^(\s*)- (\d+)(?:\.([\w.-]+))?: /, (_match, indent, index, field) => `${indent}entry ${Number(index) + 1}${field ? `, ${field}` : ""}: `).replace(/^(\s*)- /, "$1");
 }
@@ -970,6 +1135,7 @@ const describe = {
   __proto__: null,
   countsText: countsText,
   firstLine: firstLine,
+  listPlacementsText: listPlacementsText,
   messageLines: messageLines,
   pdfCell: pdfCell,
   pdfPlacementsOf: pdfPlacementsOf,
@@ -1000,7 +1166,7 @@ function schemaText(section) {
 async function fieldSnippets(context, inv, section, names) {
   const { style, run, root } = context;
   const { webFieldSnippet, etaFieldSnippet } = await import('../chunks/snippets.mjs');
-  const { existsSync } = await import('node:fs');
+  const { existsSync: existsSync2 } = await import('node:fs');
   const { join: join2 } = await import('node:path');
   const id = section.id;
   const unknown = names.filter((name) => !section.fields?.some((field) => field.path === name));
@@ -1031,7 +1197,7 @@ async function fieldSnippets(context, inv, section, names) {
   if (components.length) lines.push("", ...indented(web.map((snippet) => snippet.markup)));
   if (imports.length) lines.push("", `    import { ${imports.join(", ")} } from '@anja.codes/vitakit/shared'`);
   lines.push("");
-  if (existsSync(join2(root, "cv-tex", "templates", `${id}.eta`))) {
+  if (existsSync2(join2(root, "cv-tex", "templates", `${id}.eta`))) {
     lines.push(block("pdf", [[`cv-tex/templates/${id}.eta (yours): add inside its loop over the entries, after the notes`]]));
   } else if (inv.documents.length) {
     lines.push(block("pdf", [[`vitakit's template. \`${run.bin("vitakit", `customize ${id} --pdf --field ${names.join(" --field ")}`)}\` copies it with these lines:`]]));
@@ -1108,9 +1274,7 @@ async function explainDocument(context, inv, document) {
     lines.push(block("includes", document.placements.map((placement) => {
       const section = inv.sections.find((candidate) => candidate.id === placement.section);
       let detail = "";
-      if (placement.section === "publications") {
-        detail = inv.publications ? `${inv.publications.entries} entries in ${inv.publications.groups} groups` : "no content/publications.bib";
-      } else if (section?.problems.length) {
+      if (section?.problems.length) {
         detail = style.red("has problems");
       } else if (section) {
         const { total, steps } = explainSelection(inv.content.sections[section.id] ?? [], document.options, section.id);
@@ -1128,12 +1292,69 @@ async function explainDocument(context, inv, document) {
   } else {
     lines.push(block("includes", [["no \\vitasection or \\vitainput lines found"]]));
   }
+  if (document.publications.length) {
+    lines.push("", block("lists", document.publications.map((placement) => [
+      `line ${placement.line}`,
+      placement.list,
+      placement.heading ?? "",
+      inv.publications?.counts[placement.list] !== void 0 ? entriesText(inv.publications.counts[placement.list]) : style.red("no such list")
+    ])));
+  }
   const pdf = document.pdf ? `${document.pdf.file}${document.pdf.mtimeMs < inv.sourcesMtimeMs ? ", older than its sources" : ""}` : "not built yet";
   lines.push("", block("pdf", [[pdf]]));
   if (document.problems.length) lines.push("", style.bold("Problems"), ...problemLines(document.problems));
   lines.push("", `Build it: \`${run.bin("vitakit", `pdf ${document.name}`)}\`; per section: \`${run.bin("vitakit", "explain <section>")}\``);
   return lines;
 }
+const entriesText = (count) => `${count} ${count === 1 ? "entry" : "entries"}`;
+async function explainPublications(context, inv) {
+  const { style, run, root } = context;
+  const { loadPublicationsSchema } = await import('../chunks/bibliography.mjs').then(function (n) { return n.e; });
+  const { LISTS_FILE, describeList, loadPublicationLists } = await import('../chunks/publication-lists.mjs');
+  const lines = [style.bold("publications"), ""];
+  lines.push(block("data", [[inv.publications ? `${inv.publications.file} \xB7 ${inv.publications.entries} entries` : "no content/publications.bib"]]));
+  lines.push(block("statuses", [[existsSync(join(root, "schemas", "publications.ts")) ? "schemas/publications.ts (yours)" : `vitakit's (\`${run.bin("vitakit", "customize publications")}\` to change them)`]]));
+  const lists = await loadPublicationsSchema(root).then((schema) => loadPublicationLists(root, schema)).catch(() => void 0);
+  if (!lists) {
+    lines.push(block("lists", [[style.red(`${LISTS_FILE} has problems`)]]));
+  } else if (!Object.keys(lists).length) {
+    lines.push(block("lists", [[`none yet: \`${run.bin("vitakit", "add publication-list <name>")}\` declares one in ${LISTS_FILE}`]]));
+  } else {
+    lines.push(block("lists", [[LISTS_FILE]]));
+    lines.push(block("", Object.entries(lists).flatMap(([name, list]) => [
+      [`  ${name}`, `${entriesText(inv.publications?.counts[name] ?? 0)} \xB7 ${describeList(list)}`],
+      ["", listPlacementsText(inv, name)]
+    ])));
+  }
+  const files = [LISTS_FILE, "content/publications.bib", "schemas/publications.ts"];
+  const problems = inv.problems.filter((problem) => files.includes(problem.where));
+  if (problems.length) lines.push("", style.bold("Problems"), ...problemLines(problems));
+  lines.push("", `Show a list: <VitaPublications list="<name>" /> on a page, \\vitapublications[Heading]{<name>} in a PDF.`);
+  return lines;
+}
+async function explainList(context, inv, name) {
+  const { style, run, root } = context;
+  const { loadPublicationsSchema, readBibliography } = await import('../chunks/bibliography.mjs').then(function (n) { return n.e; });
+  const { LISTS_FILE, describeList, explainListSelection, loadPublicationLists } = await import('../chunks/publication-lists.mjs');
+  const { publicationListLine } = await import('../chunks/yaml.mjs');
+  const { readFile } = await import('node:fs/promises');
+  const schema = await loadPublicationsSchema(root);
+  const list = (await loadPublicationLists(root, schema))[name];
+  const line = publicationListLine(await readFile(join(root, LISTS_FILE), "utf8"), name);
+  const { total, steps: removed, keys } = explainListSelection(await readBibliography(join(root, "content", "publications.bib"), schema), name, list, schema);
+  const lines = [style.bold(name), ""];
+  lines.push(block("list", [[`${LISTS_FILE}${line ? `:${line}` : ""}`], [describeList(list)]]));
+  lines.push(block("shows", [
+    [`${keys.length} of ${total} publications${removed.length ? ` (${removed.map((step) => `${step.rule} \u2212${step.removed}`).join(", ")})` : ""}`],
+    ...keys.length ? [[keys.join(", ")]] : []
+  ]), "");
+  const web = inv.web.publications.filter((placement) => placement.list === name);
+  lines.push(block("website", web.length ? web.map((placement) => [placement.route ?? "", `${placement.file}:${placement.line}`, `<VitaPublications${placement.title !== void 0 ? ` title="${placement.title}"` : ""}>`]) : [["not on any page"]]));
+  const pdf = inv.documents.flatMap((document) => document.publications.filter((placement) => placement.list === name));
+  lines.push("", block("pdf", pdf.length ? pdf.map((placement) => [placement.document, `${placement.file}:${placement.line}`, `\\vitapublications${placement.heading !== void 0 ? `[${placement.heading}]` : ""}{${name}}`]) : [["not in any PDF document"]]));
+  if (!web.length && !pdf.length) lines.push("", `Show it: \`${run.bin("vitakit", `add publication-list ${name} --page /publications/`)}\`, or --document cv.`);
+  return lines;
+}
 function explainRoute(context, inv, page, route) {
   const { style } = context;
   const lines = [style.bold(route), ""];
@@ -1152,61 +1373,131 @@ function explainRoute(context, inv, page, route) {
       placement.component === "code" ? "useSection, in code" : `<${placement.component}${placement.title !== void 0 ? ` title="${placement.title}"` : ""}>`
     ])));
   }
+  const lists = inv.web.publications.filter((placement) => placement.route === route);
+  if (lists.length) {
+    lines.push("", block("lists", lists.map((placement) => [
+      placement.list ?? placement.expression ?? "(no list)",
+      `line ${placement.line}`,
+      `<VitaPublications${placement.title !== void 0 ? ` title="${placement.title}"` : ""}>`
+    ])));
+  }
   const dynamic = inv.web.dynamic.filter((usage) => usage.file === page?.vue);
   if (dynamic.length) {
     lines.push("", "Chosen in code, so not listed:", ...dynamic.map((usage) => `  line ${usage.line}  ${usage.usage}`));
   }
   return lines;
 }
+const KINDS = ["section", "document", "publication-list", "page"];
+const KIND_NAMES = { "section": "section", "document": "PDF document", "publication-list": "publication list", "page": "page" };
 const explain = {
   name: "explain",
-  summary: "where a section, PDF document or page comes from, and where it goes",
-  positionals: [{ name: "name", required: true }],
+  summary: "where a section, publication list, PDF document or page comes from, and where it goes",
+  // `<name>`, or `<kind> <name>`; the usage lines say so.
+  positionals: [{ name: "name", required: true }, { name: "name" }],
+  usage: (run) => [
+    run.bin("vitakit", "explain <name> [options]"),
+    run.bin("vitakit", "explain <kind> <name> [options]")
+  ],
   options: {
-    section: { type: "boolean", description: "the name is a section (when a document has the same name)" },
-    document: { type: "boolean", description: "the name is a PDF document (when a section has the same name)" },
     field: { type: "string", multiple: true, value: "<name>", description: "a section: lines that show this field, on the website and in the PDF" }
   },
   project: true,
   help: (run) => `
-  ${run.bin("vitakit", "explain talks")}       a section: its file, fields, pages and PDFs
-  ${run.bin("vitakit", "explain cv")}          a PDF document: what it includes, from where
-  ${run.bin("vitakit", "explain /cv/")}        a website page: its files and sections
+  ${run.bin("vitakit", "explain talks")}            a section: its file, fields, pages and PDFs
+  ${run.bin("vitakit", "explain cv")}               a PDF document: what it includes, from where
+  ${run.bin("vitakit", "explain /cv/")}             a website page: its files, sections and lists
+  ${run.bin("vitakit", "explain recent")}           a publication list: which publications, and why
+  ${run.bin("vitakit", "explain publications")}     every publication list: what it shows, and where
   ${run.bin("vitakit", "explain teaching --field evaluation")}   lines that show a field
 
+A name is enough while it is unique. To say what it is -- when a section, a
+document and a list share a name, or in a script -- put the kind first, as
+\`add\` does: ${KINDS.join(", ")}.
+
+  ${run.bin("vitakit", "explain section talks")}
+  ${run.bin("vitakit", "explain publication-list talks")}
+  ${run.bin("vitakit", "explain page cv")}
+
 For a section it shows which entries each PDF document selects, and which
 setting removed the others -- the answer to "why is this not in my PDF?".
-Never prints entry contents, only counts.`,
+For a publication list, the same: which setting removed which publications,
+and the citation keys of those it shows. Entry contents are never printed.`,
   async run(context, { positionals, values }) {
     const { inventory } = await import('../chunks/inventory.mjs');
     const inv = await inventory(context.root);
-    const name = positionals[0];
-    let lines;
-    if (name.startsWith("/")) {
-      const route = name.endsWith("/") ? name : `${name}/`;
-      lines = explainRoute(context, inv, inv.pages.find((page) => page.route === route), route);
-    } else {
-      const section = inv.sections.find((candidate) => candidate.id === name);
-      const document = inv.documents.find((candidate) => candidate.name === name);
-      if (values.section && values.document) throw new UsageError("use --section or --document, not both", "explain");
-      if (section && document && !values.section && !values.document) {
-        throw new UsageError(`"${name}" is both a section and a PDF document; add --section or --document`, "explain");
-      }
-      const fields = values.field ?? [];
-      if (fields.length && !(section && !values.document)) throw new UsageError("--field goes with a section", "explain");
-      if (section && !values.document) lines = await explainSection(context, inv, section, fields);
-      else if (document && !values.section) lines = await explainDocument(context, inv, document);
-      else {
-        const known = [
-          inv.sections.length ? `sections: ${inv.sections.map((candidate) => candidate.id).join(", ")}` : "",
-          inv.documents.length ? `documents: ${inv.documents.map((candidate) => candidate.name).join(", ")}` : ""
-        ].filter(Boolean).join("; ");
-        throw new CommandError(`nothing called "${name}"${known ? `; ${known}` : ""}. A page is explained by its route, e.g. /cv/.`);
-      }
+    const typed = positionals.length === 2;
+    const kind = typed ? positionals[0] : void 0;
+    const name = typed ? positionals[1] : positionals[0];
+    if (kind !== void 0 && !KINDS.includes(kind)) {
+      throw new UsageError(`"${kind}" is not a kind: \`explain <kind> <name>\` takes ${KINDS.join(", ")}; or a name alone`, "explain");
     }
-    context.io.out(`${lines.join("\n")}
+    const fields = values.field ?? [];
+    const out = (lines) => {
+      context.io.out(`${lines.join("\n")}
 `);
-    return 0;
+      return 0;
+    };
+    if (kind === "page" || !kind && name.startsWith("/")) {
+      const route = name === "/" || name === "index" ? "/" : `/${name.replace(/^\/|\/$/g, "")}/`;
+      return out(explainRoute(context, inv, inv.pages.find((page) => page.route === route), route));
+    }
+    if (!kind && name === "publications") return out(await explainPublications(context, inv));
+    const lists = Object.keys(inv.content.publications);
+    const section = inv.sections.find((candidate) => candidate.id === name);
+    const document = inv.documents.find((candidate) => candidate.name === name);
+    const found = [
+      ...section ? [{ kind: "section", explain: () => explainSection(context, inv, section, fields) }] : [],
+      ...document ? [{ kind: "document", explain: () => explainDocument(context, inv, document) }] : [],
+      ...lists.includes(name) ? [{ kind: "publication-list", explain: () => explainList(context, inv, name) }] : []
+    ];
+    const chosen = kind ? found.filter((candidate) => candidate.kind === kind) : found;
+    if (chosen.length > 1) {
+      throw new UsageError([
+        `"${name}" is ${chosen.map((candidate) => `a ${KIND_NAMES[candidate.kind]}`).join(" and ")}; say which:`,
+        ...chosen.map((candidate) => `  ${context.run.bin("vitakit", `explain ${candidate.kind} ${name}`)}`)
+      ].join("\n"), "explain");
+    }
+    if (chosen.length === 1) {
+      if (fields.length && chosen[0].kind !== "section") throw new UsageError("--field goes with a section", "explain");
+      return out(await chosen[0].explain());
+    }
+    if (!kind && KINDS.includes(name)) throw new UsageError(`missing <name>: \`explain ${name} <name>\``, "explain");
+    const known = [
+      inv.sections.length ? `sections: ${inv.sections.map((candidate) => candidate.id).join(", ")}` : "",
+      inv.documents.length ? `documents: ${inv.documents.map((candidate) => candidate.name).join(", ")}` : "",
+      lists.length ? `publication lists: ${lists.join(", ")}` : ""
+    ].filter(Boolean).join("; ");
+    throw new CommandError(`${kind ? `no ${KIND_NAMES[kind]}` : "nothing"} called "${name}"${known ? `; ${known}` : ""}. A page is explained by its route, e.g. /cv/.`);
+  }
+};
+
+const migrate = {
+  name: "migrate",
+  summary: "update a project written for an earlier vitakit",
+  positionals: [],
+  options: {
+    "dry-run": { type: "boolean", description: "show what would be written, write nothing" },
+    "yes": { type: "boolean", description: "ask nothing and write" }
+  },
+  project: true,
+  help: (run) => `
+After updating vitakit, changes your files where they use what it no longer
+supports. Everything is shown before it is written, and asked; what cannot be
+changed safely is listed for you to do by hand. Running it again changes
+nothing that is up to date.
+
+  ${run.bin("vitakit", "migrate --dry-run")}
+  ${run.bin("vitakit", "migrate")}
+
+Then check the project: \`${run.bin("vitakit", "validate")}\``,
+  async run(context, { values }) {
+    const { Workspace } = await import('../chunks/plan.mjs');
+    const { migratePublicationLists } = await import('../chunks/migrations.mjs');
+    const ws = new Workspace(context.root);
+    const notes = { before: [], after: [] };
+    await migratePublicationLists(context.root, ws, notes);
+    notes.after.push(`Check the project: \`${context.run.bin("vitakit", "validate")}\``);
+    return finish(context, ws, values, notes);
   }
 };
 
@@ -1278,6 +1569,7 @@ Reads your files only: no website build, no LaTeX. Entry contents are never
 printed, only how many there are.
 
 Next: \`${run.bin("vitakit", "explain <section>")}\` for the details of one section,
+\`${run.bin("vitakit", "explain publications")}\` for the publication lists,
 \`${run.bin("vitakit", "validate")}\` to check everything before building.`,
   async run({ io, style, run, root, json }) {
     const { inventory } = await import('../chunks/inventory.mjs');
@@ -1324,7 +1616,11 @@ Next: \`${run.bin("vitakit", "explain <section>")}\` for the details of one sect
     }
     const facts = [];
     if (inv.publications) {
-      facts.push([style.bold("Publications"), `${inv.publications.file} \xB7 ${inv.publications.entries} entries in ${inv.publications.groups} groups`]);
+      const { counts } = inv.publications;
+      facts.push([style.bold("Publications"), `${inv.publications.file} \xB7 ${inv.publications.entries} entries${Object.keys(counts).length ? "" : " \xB7 no lists yet (content/publication-lists.yml)"}`]);
+      for (const [name, count2] of Object.entries(counts)) {
+        facts.push(["", `  ${name}: ${count2} ${count2 === 1 ? "entry" : "entries"} \xB7 ${listPlacementsText(inv, name)}`]);
+      }
     }
     const pages = inv.pages.filter((page) => page.markdown || page.vue);
     if (pages.length) {
@@ -1464,11 +1760,11 @@ ${style.green("The generated site looks correct.")}
   }
 };
 
-const COMMANDS = [status, explain, validate, add, customize, pdf, verify, eject];
+const COMMANDS = [status, explain, validate, add, customize, pdf, verify, eject, migrate];
 const GROUPS = [
   { title: "Look", names: ["status", "explain", "validate"] },
   { title: "Build and check", names: ["pdf", "verify"] },
-  { title: "Change", names: ["add", "customize", "eject"] }
+  { title: "Change", names: ["add", "customize", "eject", "migrate"] }
 ];
 
 function version() {

package/dist/tex/templates/publications.eta

@@ -1,9 +1,11 @@
 <% if (it.groups.length) { %>
 \begin{refsection}
-\nocite{*}
+\begin{refcontext}[sorting=none]
+<%~ it.bib.cite() %>
 <% for (const group of it.groups) { %>
 <%~ it.bib.group(group) %>
-\printbibliography[check=vita-<%~ group.id %>, title={<%~ it.text(group.label) %>}, heading=subbibliography]
+\printbibliography[resetnumbers=true, check=vita-<%~ group.id %>, <% if (group.label !== undefined) { %>heading=subbibliography, title={<%~ it.text(group.label) %>}<% } else { %>heading=none<% } %>]
 <% } %>
+\end{refcontext}
 \end{refsection}
 <% } %>

package/dist/tex/vitakit-cv.cls

@@ -36,10 +36,10 @@
   \RequirePackage[backend=biber, style=numeric, sorting=ydnt,
                   defernumbers=true, maxbibnames=99, giveninits=true]{biblatex}
   %% \vitabibgroup{id}{key,key,...} defines the bibliography check `vita-id`,
-  %% which keeps exactly the listed entries. The generated publications.tex
-  %% uses one per group: vitakit decides the groups, with the website's rules
-  %% (a missing `status` is `published`, case does not matter), so the PDF
-  %% lists what the website lists. Keys are compared as strings.
+  %% which keeps exactly the listed entries. A generated list cites its keys
+  %% in the list's order and prints one bibliography per group with
+  %% sorting=none, so the PDF lists what the website lists, in its order.
+  %% Keys are compared as strings.
   \newcommand{\vitabibgroup}[2]{%
     \defbibcheck{vita-#1}{%
       \edef\vita@bibkey{\thefield{entrykey}}%
@@ -131,4 +131,15 @@
 %% for sections that bring their own structure (publications).
 \newcommand{\vitainput}[1]{\input{generated/\vita@document/#1.tex}}
 
+%% Generated profile.tex marks publication lists without entries.
+\newcommand{\vitaemptypublications}[1]{\expandafter\def\csname vita@emptylist@#1\endcsname{}}
+
+%% \vitapublications[Heading]{list} -- a list from content/publication-lists.yml,
+%% with an optional heading; neither appears when the list has no entries.
+\NewDocumentCommand{\vitapublications}{o m}{%
+  \ifcsname vita@emptylist@#2\endcsname\else
+    \IfNoValueF{#1}{\section{#1}}%
+    \input{generated/\vita@document/publications/#2.tex}%
+  \fi}
+
 \endinput