@@ -16,6 +16,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { baseHeadHtml, commercialLabel, headAssetsHtml, esc, latestAllowedDate, OG_CARD_NAME, PAGE_MODULES, sponsorButtonHtml } from "./lib/shared.mjs";
 import { filmstripHtml, groupedEntriesHtml } from "./lib/cards.mjs";
+import { guidePageHtml } from "./lib/guide-page.mjs";
+import { renderGuide } from "./lib/guide-render.mjs";
 import { categoryPageHtml } from "./lib/category-page.mjs";
 import { filmstripPick, isAttributionLicence, previewCredit, thumbRelPath } from "./lib/thumbs.mjs";
 import { parseFrontmatter, summaryFromBody } from "./lib/frontmatter.mjs";
@@ -203,7 +205,7 @@ function guideRowsHtml(guides, repo) {
   return (guides || [])
     .map(
       (g) =>
-        `<li><a href="${esc(`${repo}/blob/main/${g.path}`)}" rel="noopener noreferrer">${esc(g.title)}<span>${esc(g.path)}</span></a></li>`
+        `<li><a href="guide/${esc(g.id)}/">${esc(g.title)}<span>${esc(g.path)}</span></a></li>`
     )
     .join("\n");
 }
@@ -484,6 +486,44 @@ function writeCategoryPages({ entries, config, stats, stamp, hasCard, now }) {
   return { written };
 }
 
+/**
+ * docs/ guides as guide/<id>/ pages. Links to entries go to their pages,
+ * links to another guide go to its page, anything else to GitHub.
+ */
+function writeGuidePages({ entries, config, stats, stamp, hasCard }) {
+  const written = [];
+  const errors = [];
+  const resolverFor = linkResolvers(entries, config, "../../entry/");
+  const guideByPath = new Map((config.guides || []).map((g) => [g.path, g.id]));
+  for (const guide of config.guides || []) {
+    const inner = resolverFor({ path: guide.path });
+    const resolveLink = (raw) => {
+      const m = String(raw).match(/^([^?#]*)((?:\?[^#]*)?(?:#.*)?)$/);
+      if (m && m[1] && !/^[a-z][a-z0-9+.-]*:/i.test(raw)) {
+        let repoPath = null;
+        try {
+          repoPath = path.posix.normalize(path.posix.join(path.posix.dirname(guide.path), decodeURI(m[1])));
+        } catch {
+          // A malformed link falls through to the entry resolver, which reports it.
+        }
+        if (repoPath && guideByPath.has(repoPath)) {
+          const id = guideByPath.get(repoPath);
+          return { href: id === guide.id ? m[2] || "#content" : `../${id}/${m[2]}`, external: false };
+        }
+      }
+      return inner(raw);
+    };
+    try {
+      const rendered = renderGuide(fs.readFileSync(path.join(ROOT, guide.path), "utf8"), { file: guide.path, resolveLink });
+      writeOut(path.join("guide", guide.id, "index.html"), guidePageHtml({ guide, rendered, site: config.site, stamp, total: stats.total, hasCard }));
+      written.push(`guide/${guide.id}/index.html`);
+    } catch (err) {
+      errors.push(err.message);
+    }
+  }
+  return { written, errors };
+}
+
 /** Runs the page checks over dist-relative files. */
 function checkPages(files) {
   // Link targets resolve against what this build produced, not what is on
@@ -637,19 +677,21 @@ function main() {
   const categoriesInSitemap = Object.keys(config.categories)
     .filter((cat) => visible.some((e) => e.category === cat))
     .map((id) => ({ id, lastmod: stamp }));
-  writeOut("sitemap.xml", sitemapXml({ site: config.site, entries: visible, stacks, stamp, modified: lastCommitDates(), categories: categoriesInSitemap }));
+  writeOut("sitemap.xml", sitemapXml({ site: config.site, entries: visible, stacks, stamp, modified: lastCommitDates(), categories: categoriesInSitemap, guides: config.guides }));
   writeOut("robots.txt", robotsTxt(config.site));
   writeOut("404.html", notFoundHtml(config.site));
   writeOut(path.join("freshness", "index.html"), freshnessPageHtml({ stats: fresh, site: config.site, stamp, total: stats.total, hasCard }));
 
   const pages = writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now, usedIn });
   const stackPages = writeStackPages({ stacks, entries, config, stats, stamp, hasCard, now });
   const categoryPages = writeCategoryPages({ entries: visible, config, stats, stamp, hasCard, now });
+  const guidePages = writeGuidePages({ entries, config, stats, stamp, hasCard });
   const pageErrors = [
     ...stackErrors,
     ...pages.errors,
     ...stackPages.errors,
-    ...checkPages(["index.html", "freshness/index.html", ...pages.written, ...stackPages.written, ...categoryPages.written]),
+    ...guidePages.errors,
+    ...checkPages(["index.html", "freshness/index.html", ...pages.written, ...stackPages.written, ...categoryPages.written, ...guidePages.written]),
   ];
   if (pageErrors.length) {
     console.error(`Page build failed (${pageErrors.length}):`);
@@ -660,7 +702,7 @@ function main() {
   // After the page gate: every body link has resolved by now, and the llms
   // files read links with the same LINK_RE, so they cannot hit a link error
   // of their own.
-  writeOut("llms.txt", llmsTxt({ entries, site: config.site, categories: config.categories, stacks }));
+  writeOut("llms.txt", llmsTxt({ entries, site: config.site, categories: config.categories, stacks, guides: config.guides }));
   writeOut(
     "llms-full.txt",
     llmsFullTxt({
@@ -681,7 +723,7 @@ function main() {
     `Built ${entries.length} entries → site/dist (${stats.active} active, ${stats.commercialOk} commercial-ok, ${stats.commercialVaries} per-file)`
   );
   console.log(
-    `Prerendered ${visible.length} entry rows into index.html; wrote ${pages.written.length} entry pages, ${stackPages.written.length} stack pages, ${categoryPages.written.length} category pages, sitemap.xml, robots.txt, 404.html, freshness/index.html`
+    `Prerendered ${visible.length} entry rows into index.html; wrote ${pages.written.length} entry pages, ${stackPages.written.length} stack pages, ${categoryPages.written.length} category pages, ${guidePages.written.length} guide pages, sitemap.xml, robots.txt, 404.html, freshness/index.html`
   );
   console.log(`${writes} of ${produced.size} output files changed${clean ? " (clean build)" : ""}; ${((Date.now() - started) / 1000).toFixed(1)}s`);
 }
 
@@ -78,7 +78,7 @@ ${grid}
     <footer class="footer">
       <p>Catalog metadata is CC0. Linked assets keep their own licences. This is the catalog's reading of each licence, not legal advice: re-check the live source before shipping.</p>
       <p class="footer-credit">${PREVIEW_CREDIT_LINE}</p>
-      <p><a href="../../freshness/">Licence freshness</a> · <a href="../../data.json">data.json</a> · <a href="../../catalog.csv">CSV</a> · <a href="../../feed.xml">feed</a> · <a href="https://github.com/TMHSDigital/Free-Game-Dev-Assets/blob/main/docs/data.md">Use the data</a></p>
+      <p><a href="../../freshness/">Licence freshness</a> · <a href="../../data.json">data.json</a> · <a href="../../catalog.csv">CSV</a> · <a href="../../feed.xml">feed</a> · <a href="../../guide/data/">Use the data</a></p>
       <p class="footer-sponsor">${sponsorButtonHtml()}</p>
       <p class="footer-stamp">Built ${esc(stamp)} from ${total} catalog entries.</p>
     </footer>
 
@@ -83,7 +83,7 @@ export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml,
   const rows = [
     // Usable in one engine only: the first thing a reader must know.
     entry.engine_lock ? ["Engine lock", esc(ENGINE_LOCK_NOTES[entry.engine_lock] || entry.engine_lock)] : null,
-    ["Licence", esc(licence)],
+    ["Licence", `${esc(licence)} <a class="facts-guide" href="../../guide/licenses/">what it means</a>`],
     ["Commercial use", esc(commercialLabel(entry.commercial))],
     ["Credit", esc(c.value)],
     ["Status", `${esc(entry.status)}: ${esc(STATUS_NOTES[entry.status] || "")}`],
@@ -177,7 +177,7 @@ export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml,
     <footer class="footer">
       <p>Catalog metadata is CC0. Linked assets keep their own licences. This is the catalog's reading of each licence, not legal advice: re-check the live source before shipping.</p>
       <p class="footer-credit">${PREVIEW_CREDIT_LINE}</p>
-      <p><a href="../../freshness/">Licence freshness</a> · <a href="../../data.json">data.json</a> · <a href="../../catalog.csv">CSV</a> · <a href="../../feed.xml">feed</a> · <a href="https://github.com/TMHSDigital/Free-Game-Dev-Assets/blob/main/docs/data.md">Use the data</a></p>
+      <p><a href="../../freshness/">Licence freshness</a> · <a href="../../data.json">data.json</a> · <a href="../../catalog.csv">CSV</a> · <a href="../../feed.xml">feed</a> · <a href="../../guide/data/">Use the data</a></p>
       <p class="footer-sponsor">${sponsorButtonHtml()}</p>
       <p class="footer-stamp">Built ${esc(stamp)} from ${total} catalog entries.</p>
     </footer>
 
@@ -12,14 +12,15 @@ import { esc } from "./shared.mjs";
  * catalog date (`verified`, `walked`) and the file's last commit date from
  * `modified` (repo path => YYYY-MM-DD), falling back to the build date.
  */
-export function sitemapXml({ site, entries, stacks = [], stamp, modified = new Map(), categories = [] }) {
+export function sitemapXml({ site, entries, stacks = [], stamp, modified = new Map(), categories = [], guides = [] }) {
   const base = String(site.siteUrl).replace(/\/+$/, "");
   const latest = (...dates) => dates.filter(Boolean).sort().pop() || stamp;
   const url = (loc, lastmod) => `  <url><loc>${esc(loc)}</loc><lastmod>${esc(lastmod)}</lastmod></url>`;
   const urls = [
     url(`${base}/`, stamp),
     url(`${base}/freshness/`, stamp),
     ...categories.map((c) => url(`${base}/category/${c.id}/`, c.lastmod || stamp)),
+    ...guides.map((g) => url(`${base}/guide/${g.id}/`, modified.get(g.path) || stamp)),
     ...stacks.map((s) => url(`${base}/stack/${s.meta.id}/`, latest(s.meta.walked, modified.get(s.rel)))),
     ...entries.map((e) => url(`${base}/entry/${e.id}/`, latest(e.verified, modified.get(e.path)))),
   ];
 
@@ -137,7 +137,7 @@ export function freshnessPageHtml({ stats, site, stamp, total, hasCard }) {
     </main>
     <footer class="footer">
       <p>Catalog metadata is CC0. Linked assets keep their own licences. This is the catalog's reading of each licence, not legal advice: re-check the live source before shipping.</p>
-      <p><a href="../data.json">data.json</a> · <a href="../catalog.csv">CSV</a> · <a href="../feed.xml">feed</a> · <a href="https://github.com/TMHSDigital/Free-Game-Dev-Assets/blob/main/docs/data.md">Use the data</a></p>
+      <p><a href="../data.json">data.json</a> · <a href="../catalog.csv">CSV</a> · <a href="../feed.xml">feed</a> · <a href="../guide/data/">Use the data</a></p>
       <p class="footer-sponsor">${sponsorButtonHtml()}</p>
       <p class="footer-stamp">Built ${esc(stamp)} from ${total} catalog entries.</p>
     </footer>
 
@@ -0,0 +1,71 @@
+/** A guide from docs/ as a site page: the site's head, nav, breadcrumb and footer around the rendered guide. Pure. */
+import { baseHeadHtml, breadcrumbLd, clipText, esc, SEO_DESCRIPTION_MAX, SEO_TITLE_MAX, sponsorButtonHtml } from "./shared.mjs";
+import { scriptJson } from "./entry-page.mjs";
+import { plainText } from "./guide-render.mjs";
+
+export function guidePageUrl(site, id) {
+  return `${String(site.siteUrl).replace(/\/+$/, "")}/guide/${id}/`;
+}
+
+export function guidePageHtml({ guide, rendered, site, stamp, total, hasCard }) {
+  const url = guidePageUrl(site, guide.id);
+  const title = `${guide.title} | ${site.title}`;
+  const description = clipText(plainText(rendered.firstParagraph) || guide.title, SEO_DESCRIPTION_MAX);
+  const edit = `${site.repo}/blob/main/${guide.path}`;
+  const ld = {
+    "@context": "https://schema.org",
+    "@type": "Article",
+    headline: plainText(rendered.title),
+    url,
+    isPartOf: { "@type": "WebSite", name: site.title, url: site.siteUrl },
+    breadcrumb: breadcrumbLd([
+      { name: site.title, url: site.siteUrl },
+      { name: "Guides", url: `${String(site.siteUrl).replace(/\/+$/, "")}/#guides` },
+      { name: guide.title, url },
+    ]),
+  };
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${esc(clipText(title, SEO_TITLE_MAX))}</title>
+    <meta name="description" content="${esc(description)}" />
+    ${baseHeadHtml({ site, title, description, url, type: "article", hasCard, root: "../../" })}
+    <script type="application/ld+json">${scriptJson(ld)}</script>
+  </head>
+  <body>
+    <a class="skip-link" href="#content">Skip to the guide</a>
+    <header class="topbar">
+      <a class="brand" href="../../">Free Game Dev Assets</a>
+      <nav class="topnav" aria-label="Primary">
+        <a href="../../#catalog">Catalog</a>
+        <a href="../../#stacks">Stacks</a>
+        <a href="../../#starters">Starters</a>
+        <a href="../../#guides">Guides</a>
+        <a href="${esc(site.repo)}" rel="noopener noreferrer">GitHub</a>
+        <span class="nav-sponsor">${sponsorButtonHtml()}</span>
+      </nav>
+    </header>
+    <main class="section entry-page guide-page" id="content">
+      <nav class="breadcrumb" aria-label="Breadcrumb">
+        <a href="../../#catalog">Catalog</a> <span aria-hidden="true">/</span>
+        <a href="../../#guides">Guides</a> <span aria-hidden="true">/</span>
+        <span aria-current="page">${esc(guide.title)}</span>
+      </nav>
+      <h1>${esc(plainText(rendered.title))}</h1>
+      <div class="entry-body guide-body">
+${rendered.html}
+      </div>
+      <p class="page-actions"><a class="btn-ghost" href="${esc(edit)}" rel="noopener noreferrer">Edit this guide on GitHub</a></p>
+    </main>
+    <footer class="footer">
+      <p>Catalog metadata is CC0. Linked assets keep their own licences. This is the catalog's reading of each licence, not legal advice: re-check the live source before shipping.</p>
+      <p><a href="../../freshness/">Licence freshness</a> · <a href="../../data.json">data.json</a> · <a href="../../catalog.csv">CSV</a> · <a href="../../feed.xml">feed</a> · <a href="../data/">Use the data</a></p>
+      <p class="footer-sponsor">${sponsorButtonHtml()}</p>
+      <p class="footer-stamp">Built ${esc(stamp)} from ${total} catalog entries.</p>
+    </footer>
+  </body>
+</html>
+`;
+}
@@ -0,0 +1,166 @@
+/**
+ * Renders a guide in docs/ for its site page. Guides use more markdown than
+ * entry bodies (tables, fenced code, blockquotes, numbered lists, ### headings),
+ * so they get their own renderer; renderBlocks stays strict for entries.
+ * Inline markup and links go through renderInline and the caller's resolver.
+ * Images and raw HTML still fail the build, as on entry pages. Pure.
+ */
+import { esc } from "./shared.mjs";
+import { MarkdownError, renderInline } from "./markdown.mjs";
+
+/** GitHub's heading anchor, so links written for GitHub (licenses.md#cc-by) land here too. */
+export function headingSlug(text) {
+  return String(text)
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+    .replace(/ /g, "-");
+}
+
+/** Table cells, split on pipes outside code spans; a leading and trailing pipe are dropped. */
+function cells(line) {
+  const out = [];
+  let cur = "";
+  let code = false;
+  const s = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (ch === "\\" && s[i + 1] === "|") {
+      cur += "|";
+      i += 1;
+    } else if (ch === "`") {
+      code = !code;
+      cur += ch;
+    } else if (ch === "|" && !code) {
+      out.push(cur.trim());
+      cur = "";
+    } else cur += ch;
+  }
+  out.push(cur.trim());
+  return out;
+}
+
+const isSeparator = (line) => /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/.test(line);
+
+/**
+ * `{ title, html, firstParagraph }`. The first `# ` heading is the page
+ * title (the template prints it as the h1); later `#` headings are refused.
+ */
+export function renderGuide(md, { file, resolveLink }) {
+  const ls = String(md).replace(/\r\n?/g, "\n").split("\n");
+  const inline = (t) => renderInline(t, resolveLink);
+  const html = [];
+  const seen = new Map();
+  let title = "";
+  let firstParagraph = "";
+  let i = 0;
+  const fail = (n, what) => {
+    throw new MarkdownError(`${file}:${n + 1}: ${what} is not supported on guide pages`);
+  };
+  const isBlockStart = (l) => /^\s*(```|>|\||#{1,6}\s|[-*]\s|\d+[.)]\s)/.test(l);
+
+  while (i < ls.length) {
+    const line = ls[i];
+    if (!line.trim()) {
+      i += 1;
+      continue;
+    }
+    if (/^\s*!\[/.test(line)) fail(i, "an image");
+    if (/^\s*<(?!https?:\/\/)[A-Za-z!/]/.test(line)) fail(i, "raw HTML");
+
+    // Fenced code: literal, escaped.
+    if (/^\s*```/.test(line)) {
+      const lang = line.trim().slice(3).trim();
+      const body = [];
+      i += 1;
+      while (i < ls.length && !/^\s*```/.test(ls[i])) body.push(ls[i++]);
+      if (i >= ls.length) fail(i - 1, "an unclosed code fence");
+      i += 1;
+      html.push(`<pre class="guide-code"${lang ? ` data-lang="${esc(lang)}"` : ""}><code>${esc(body.join("\n"))}</code></pre>`);
+      continue;
+    }
+
+    const h = line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+    if (h) {
+      const level = h[1].length;
+      if (level === 1) {
+        if (title) fail(i, "a second top-level heading");
+        title = h[2];
+        i += 1;
+        continue;
+      }
+      const base = headingSlug(h[2]);
+      const n = seen.get(base) || 0;
+      seen.set(base, n + 1);
+      const id = n ? `${base}-${n}` : base;
+      const tag = `h${Math.min(level, 4)}`;
+      html.push(`<${tag} id="${esc(id)}">${inline(h[2])}</${tag}>`);
+      i += 1;
+      continue;
+    }
+
+    if (/^\s*\|/.test(line)) {
+      const rows = [];
+      while (i < ls.length && /^\s*\|/.test(ls[i])) rows.push(ls[i++]);
+      if (rows.length < 2 || !isSeparator(rows[1])) fail(i - rows.length, "a table without a header separator");
+      const head = cells(rows[0]);
+      const body = rows.slice(2).map(cells);
+      html.push(
+        `<div class="table-wrap"><table class="guide-table"><thead><tr>${head.map((c) => `<th scope="col">${inline(c)}</th>`).join("")}</tr></thead><tbody>` +
+          body.map((r) => `<tr>${head.map((_, k) => `<td>${inline(r[k] || "")}</td>`).join("")}</tr>`).join("") +
+          `</tbody></table></div>`
+      );
+      continue;
+    }
+
+    if (/^\s*>/.test(line)) {
+      const quote = [];
+      while (i < ls.length && /^\s*>/.test(ls[i])) quote.push(ls[i++].replace(/^\s*>\s?/, ""));
+      const paras = quote.join("\n").split(/\n\s*\n/).map((p) => `<p>${inline(p.replace(/\n/g, " ").trim())}</p>`);
+      html.push(`<blockquote>${paras.join("")}</blockquote>`);
+      continue;
+    }
+
+    const listRe = /^\s*([-*]|\d+[.)])\s+(.*)$/;
+    const li = line.match(listRe);
+    if (li) {
+      const ordered = /\d/.test(li[1]);
+      const items = [];
+      while (i < ls.length) {
+        const m = ls[i].match(listRe);
+        if (m && /\d/.test(m[1]) === ordered) {
+          items.push(m[2]);
+          i += 1;
+        } else if (items.length && ls[i].trim() && /^\s+/.test(ls[i]) && !isBlockStart(ls[i])) {
+          items[items.length - 1] += ` ${ls[i].trim()}`;
+          i += 1;
+        } else break;
+      }
+      const tag = ordered ? "ol" : "ul";
+      html.push(`<${tag}>${items.map((t) => `<li>${inline(t)}</li>`).join("")}</${tag}>`);
+      continue;
+    }
+
+    const para = [];
+    while (i < ls.length && ls[i].trim() && !isBlockStart(ls[i])) para.push(ls[i++].trim());
+    if (!para.length) {
+      // A line that looks like a block start but matched nothing above.
+      para.push(ls[i++].trim());
+    }
+    const text = para.join(" ");
+    if (!firstParagraph) firstParagraph = text;
+    html.push(`<p>${inline(text)}</p>`);
+  }
+  if (!title) throw new MarkdownError(`${file}:1: a guide needs a "# " title`);
+  return { title, html: html.join("\n"), firstParagraph };
+}
+
+/** Markdown inline marks and links reduced to plain text, for a meta description. */
+export function plainText(md) {
+  return String(md)
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}