@@ -6,7 +6,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { commercialLabel, esc, PERSPECTIVE_LABELS, verifiedAge } from "./lib/shared.mjs";
+import { commercialLabel, esc, PERSPECTIVE_LABELS, unquoteScalar, verifiedAge } from "./lib/shared.mjs";
 import { entryPageHtml } from "./lib/entry-page.mjs";
 import { LinkError, makeLinkResolver } from "./lib/links.mjs";
 import { llmsFullTxt, llmsTxt } from "./lib/llms.mjs";
@@ -38,7 +38,7 @@ function parseScalar(raw) {
     (v.startsWith('"') && v.endsWith('"')) ||
     (v.startsWith("'") && v.endsWith("'"))
   ) {
-    return v.slice(1, -1);
+    return unquoteScalar(v);
   }
   if (v.startsWith("[") && v.endsWith("]")) {
     const inner = v.slice(1, -1).trim();
@@ -382,16 +382,22 @@ function copyDir(src, dest) {
   }
 }
 
-/** Writes dist/entry/<id>/index.html for every entry. */
-function writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now }) {
-  const errors = [];
-  const written = [];
+/** Returns entry => link resolver for links in that entry's body. */
+function linkResolvers(entries, config) {
   const idByPath = new Map(entries.map((e) => [e.path, e.id]));
   const kindOf = (repoPath) => {
     const full = path.join(ROOT, repoPath);
     if (!fs.existsSync(full)) return null;
     return fs.statSync(full).isDirectory() ? "dir" : "file";
   };
+  return (entry) => makeLinkResolver({ entryPath: entry.path, idByPath, repo: config.site.repo, kindOf });
+}
+
+/** Writes dist/entry/<id>/index.html for every entry. */
+function writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now }) {
+  const errors = [];
+  const written = [];
+  const resolverFor = linkResolvers(entries, config);
   // Prev/next follow the homepage's default order: category, then name.
   const visible = entries.filter((e) => e.status !== "deprecated");
   const neighbours = new Map();
@@ -403,7 +409,7 @@ function writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now }
     const body = bodies.get(entry.id) || "";
     const file = `${entry.path} (body)`;
     try {
-      const resolveLink = makeLinkResolver({ entryPath: entry.path, idByPath, repo: config.site.repo, kindOf });
+      const resolveLink = resolverFor(entry);
       const { lead, rest, restFirstLine } = splitEntryBody(body);
       const leadHtml = renderBlocks(lead, { file, resolveLink });
       const restHtml = renderBlocks(rest, { file, resolveLink, firstLine: restFirstLine });
@@ -530,11 +536,6 @@ function main() {
   fs.writeFileSync(path.join(DIST, "sitemap.xml"), sitemapXml(config.site, visible));
   fs.writeFileSync(path.join(DIST, "robots.txt"), robotsTxt(config.site));
   fs.writeFileSync(path.join(DIST, "404.html"), notFoundHtml(config.site));
-  fs.writeFileSync(path.join(DIST, "llms.txt"), llmsTxt({ entries, site: config.site, categories: config.categories }));
-  fs.writeFileSync(
-    path.join(DIST, "llms-full.txt"),
-    llmsFullTxt({ entries, site: config.site, categories: config.categories, bodies })
-  );
 
   const pages = writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now });
   const pageErrors = [...pages.errors, ...checkPages(["index.html", ...pages.written])];
@@ -544,6 +545,20 @@ function main() {
     process.exit(1);
   }
 
+  // After the page gate: every body link has resolved by now, so the llms
+  // files cannot hit a link error of their own.
+  fs.writeFileSync(path.join(DIST, "llms.txt"), llmsTxt({ entries, site: config.site, categories: config.categories }));
+  fs.writeFileSync(
+    path.join(DIST, "llms-full.txt"),
+    llmsFullTxt({
+      entries,
+      site: config.site,
+      categories: config.categories,
+      bodies,
+      resolverFor: linkResolvers(entries, config),
+    })
+  );
+
   console.log(
     `Built ${entries.length} entries → site/dist (${stats.active} active, ${stats.commercialOk} commercial-ok, ${stats.commercialVaries} per-file)`
   );
 
@@ -166,6 +166,30 @@ has("full carries notes", lf, "- catch one");
 lacks("full leaves evidence out", lf, "## Evidence");
 has("full carries the source", lf, "Source: https://src.test/");
 
+/* final review fixes ------------------------------------------------------- */
+import { unquoteScalar } from "./shared.mjs";
+eq("escaped double quote", renderInline('a \\"q\\" b', passLink), "a &quot;q&quot; b");
+eq("escaped comma", renderInline("x\\,y", passLink), "x,y");
+eq("yaml double-quoted escapes", unquoteScalar('"Music \\"{t}\\" by a\\\\b"'), 'Music "{t}" by a\\b');
+eq("yaml single-quoted escape", unquoteScalar("'it''s'"), "it's");
+eq("yaml unquoted passes through", unquoteScalar("plain"), "plain");
+const longLead = `Lead ${"word ".repeat(60)}with [k](k.md) at the end.`;
+const lfLinks = llmsFullTxt({
+  entries: [{ ...llmsEntries[0], summary: "Short…" }],
+  site,
+  categories: cats,
+  bodies: new Map([["a1", `# A\n\n${longLead}\n\n## Notes\n\n- see [o](../audio/o.md) and [d](../../docs/p.md)\n- read [\`docs/p.md\`](../../docs/p.md); \`[x](y)\` stays literal`]]),
+  resolverFor: () => (href) =>
+    href.endsWith("o.md") ? { href: "../o/", external: false } : href.endsWith("k.md") ? { href: "../k/", external: false } : { href: "https://github.com/o/r/blob/main/docs/p.md", external: true },
+});
+has("full uses the whole lead", lfLinks, "word with [k](https://x.test/s/entry/k/) at the end.");
+lacks("full does not use the cut summary", lfLinks, "Short…");
+has("full notes link to entry pages", lfLinks, "[o](https://x.test/s/entry/o/)");
+has("full notes link to GitHub", lfLinks, "[d](https://github.com/o/r/blob/main/docs/p.md)");
+lacks("full has no relative links", lfLinks, "](../");
+has("full rewrites a link whose label is code", lfLinks, "[`docs/p.md`](https://github.com/o/r/blob/main/docs/p.md)");
+has("full leaves links inside code alone", lfLinks, "`[x](y)` stays literal");
+
 /* report (keep last) ------------------------------------------------------ */
 if (failures.length) {
   console.error(`lib.test failed (${failures.length}):`);
 
@@ -1,7 +1,31 @@
 /** Plain-text indexes of the catalog for AI assistants (llmstxt.org format). */
-import { sectionMarkdown } from "./markdown.mjs";
+import { sectionMarkdown, splitEntryBody } from "./markdown.mjs";
 import { commercialLabel, entryPageUrl } from "./shared.mjs";
 
+/** The first paragraph of the body before its first `##`, lines joined. */
+function leadParagraph(body) {
+  const first = splitEntryBody(body)
+    .lead.split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .find((p) => p && !p.startsWith("#"));
+  return first ? first.split("\n").map((l) => l.trim()).join(" ") : "";
+}
+
+/** Markdown links made absolute: this file is read on its own, far from the repo. */
+function absoluteLinks(md, resolveLink, pageUrl) {
+  if (!resolveLink) return md;
+  // Code spans are literal: set them aside so a link-shaped span is left
+  // alone, while a link whose label is code is still rewritten.
+  const spans = [];
+  const out = md
+    .replace(/`[^`]*`/g, (span) => `\u0000${spans.push(span) - 1}\u0000`)
+    .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, href) => {
+      const r = resolveLink(href);
+      return `[${label}](${r.external ? r.href : new URL(r.href, pageUrl).href})`;
+    });
+  return out.replace(/\u0000(\d+)\u0000/g, (_, i) => spans[Number(i)]);
+}
+
 const creditWord = (e) =>
   e.attribution_required === true ? "credit required" : e.attribution_required === false ? "no credit required" : "credit unclear";
 
@@ -31,14 +55,19 @@ export function llmsTxt({ entries, site, categories }) {
   return `${out.join("\n")}\n`;
 }
 
-export function llmsFullTxt({ entries, site, categories, bodies }) {
+export function llmsFullTxt({ entries, site, categories, bodies, resolverFor }) {
   const out = [header(site)];
   for (const g of groups(entries, categories)) {
     out.push(`\n## ${g.label}\n`);
     for (const e of g.items) {
-      const notes = sectionMarkdown(bodies.get(e.id) || "", "Notes");
+      const body = bodies.get(e.id) || "";
+      const page = entryPageUrl(site, e.id);
+      const resolveLink = resolverFor ? resolverFor(e) : null;
+      const lead = absoluteLinks(leadParagraph(body) || e.summary || "", resolveLink, page);
+      const notesMd = sectionMarkdown(body, "Notes");
+      const notes = notesMd ? absoluteLinks(notesMd, resolveLink, page) : null;
       out.push(
-        `### ${e.name}\n\nPage: ${entryPageUrl(site, e.id)}\nSource: ${e.url}\nLicence: ${facts(e)}; verified ${e.verified}\n\n${e.summary || ""}${notes ? `\n\n${notes}` : ""}\n`
+        `### ${e.name}\n\nPage: ${page}\nSource: ${e.url}\nLicence: ${facts(e)}; verified ${e.verified}\n\n${lead}${notes ? `\n\n${notes}` : ""}\n`
       );
     }
   }
 
@@ -27,8 +27,8 @@ export function renderInline(text, resolveLink) {
   let s = String(text);
   // Code spans first: their contents are literal.
   s = s.replace(/`([^`]+)`/g, (_, code) => keep(`<code>${esc(code)}</code>`));
-  // Backslash escapes.
-  s = s.replace(/\\([\\`*_[\]()#+\-.!|<>])/g, (_, ch) => keep(esc(ch)));
+  // Backslash escapes: any ASCII punctuation, as in CommonMark.
+  s = s.replace(/\\([!-/:-@[-`{-~])/g, (_, ch) => keep(esc(ch)));
   // Links. The label keeps bold, italic and code; the href goes through the resolver.
   s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, href) => {
     const { href: out, external } = resolveLink(href);
 
@@ -49,3 +49,12 @@ export function commercialLabel(v) {
 export function entryPageUrl(site, id) {
   return `${String(site.siteUrl).replace(/\/+$/, "")}/entry/${id}/`;
 }
+
+/** A YAML scalar without its quotes, with the quote escapes undone. */
+export function unquoteScalar(v) {
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    return v.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1).replaceAll("''", "'");
+  return v;
+}
@@ -460,7 +460,12 @@
     } catch {
       return;
     }
-    if (y !== null) requestAnimationFrame(() => window.scrollTo(0, Number(y)));
+    // Only Back and Forward return to a position. A link to the homepage
+    // (the brand, the breadcrumb) is a new visit and starts where it asks.
+    const nav = performance.getEntriesByType("navigation")[0];
+    if (y !== null && nav && nav.type === "back_forward") {
+      requestAnimationFrame(() => window.scrollTo(0, Number(y)));
+    }
   }
 
   // Restored from the back/forward cache: the page kept its own position,
@@ -517,6 +522,8 @@
     // The whole card is the title link (a stretched ::after), so every click
     // that leaves for an entry page lands here.
     $("#entry-grid").addEventListener("click", (e) => {
+      // A modified click opens a new tab and this page stays where it is.
+      if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
       if (e.target.closest("a.entry-link")) rememberScroll();
     });