@heroiclands/package-build 23.7.1 → 23.9.0

package/engine/lexical-sections.mjs

@@ -0,0 +1,247 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Automatic dictionaries and glossaries, derived synchronously from the same
+ * rows their SQL layouts read. An existing anchored section receives its list
+ * after its authored text; otherwise the note receives a new final section.
+ * The insertion and the publisher read the same Markdown, on every surface.
+ *
+ * @module
+ */
+
+import { renderAddress } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+import { renderDictionary, renderGlossary } from "./dictionary-layout.mjs";
+import { DICTIONARY_COLUMNS, TERM_COLUMNS, dictionaryAndTermRows } from "./dictionary-rows.mjs";
+import { glossaryLanguage } from "./glossary-language.mjs";
+import { scanHeadingAttributes } from "./heading-attributes.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+
+/** The automatic lexical sections and the authored anchors each may reuse. */
+export const LEXICAL_SECTIONS = Object.freeze(
+    [
+        {
+            slug: "dictionary",
+            heading: "Dictionary",
+            aliases: ["dictionary", "lexicon"],
+            dataKey: "words",
+            types: [{ type: "skill", subType: "language" }],
+        },
+        {
+            slug: "glossary",
+            heading: "Glossary",
+            aliases: ["glossary"],
+            dataKey: "glossary",
+            types: [{ type: "lore", subType: "culture" }, { type: "affiliation" }],
+        },
+    ].map((section) =>
+        Object.freeze({
+            ...section,
+            aliases: Object.freeze(section.aliases),
+            types: Object.freeze(section.types.map((kind) => Object.freeze(kind))),
+        }),
+    ),
+);
+
+/** The lexical section this note's own nonempty frontmatter requests. */
+function sectionFor(record) {
+    return LEXICAL_SECTIONS.find(
+        (section) =>
+            section.types.some(
+                (kind) =>
+                    record?.type === kind.type &&
+                    (!kind.subType || record.subType === kind.subType),
+            ) &&
+            Array.isArray(record.data?.[section.dataKey]) &&
+            record.data[section.dataKey].length > 0,
+    );
+}
+
+/**
+ * Whether frontmatter supplies an automatic lexical section, including on a
+ * note with no authored prose. Such a note has content and is not a stub.
+ *
+ * @param {object|null|undefined} frontmatter - A note or its index record.
+ * @returns {boolean} Whether its own nonempty words or glossary qualify.
+ */
+export function hasLexicalEntries(frontmatter) {
+    return Boolean(sectionFor(frontmatter));
+}
+
+/** A note's canonical identity, including a data-only note that was a stub. */
+const keyOf = (record) =>
+    record?.package && record.type && record.shortcode ?
+        renderAddress({
+            package: record.package,
+            system: "note",
+            type: record.type,
+            shortcode: record.shortcode,
+        })
+    :   undefined;
+
+/**
+ * One automatic section, whose rows are rendered at its containing heading's
+ * level when inserted.
+ *
+ * @typedef {object} LexicalSection
+ * @property {string} slug - The canonical section anchor and layout name.
+ * @property {string} heading - The heading used when none is authored.
+ * @property {readonly string[]} aliases - Authored heading anchors to reuse.
+ * @property {{columns: string[], rows: object[]}} result - The selected rows.
+ * @property {import("./dictionary-layout.mjs").LayoutOptions} options - Labels,
+ *   linkability and the page's language, shared by every surface.
+ */
+
+/**
+ * Automatic lexical sections by owning note's canonical Address. Only
+ * nonempty own `words` or `glossary` arrays qualify. A glossary selects only
+ * explicitly declared owner entries, including a rank only when named there.
+ *
+ * @param {object[]} records - The audience's visible index records.
+ * @param {object[]} [all=records] - Complete records for lineage traversal.
+ * @returns {Map<string, LexicalSection[]>} Sections by owning Address.
+ */
+export function lexicalSectionsFor(records, all = records) {
+    const visible = encodeAddresses(records).filter(isNoteRecord);
+    const complete = encodeAddresses(all).filter(isNoteRecord);
+    const byKey = new Map(visible.map((record) => [keyOf(record), record]));
+    const addressContext = {
+        types: new Set(complete.map((record) => record.type)),
+        packages: new Set(complete.map((record) => record.package)),
+        system: "note",
+    };
+    const { dictionary, terms } = dictionaryAndTermRows(visible, complete);
+    const sections = new Map();
+    for (const [key, record] of byKey) {
+        if (!key) continue;
+        const spec = sectionFor(record);
+        if (!spec) continue;
+        const language = spec.slug === "dictionary";
+        const rows =
+            language ?
+                dictionary.filter((row) => row.language === key)
+            :   terms.filter((row) => row.owner === key && row.origins.includes("glossary"));
+        const pageLanguage = glossaryLanguage(undefined, record, {
+            self: key,
+            keyOf: (value) => (typeof value === "string" ? value : undefined),
+            lookup: (address) => byKey.get(address),
+        });
+        sections.set(key, [
+            {
+                slug: spec.slug,
+                heading: spec.heading,
+                aliases: spec.aliases,
+                result: { columns: [...(language ? DICTIONARY_COLUMNS : TERM_COLUMNS)], rows },
+                options: {
+                    addressContext: { ...addressContext, package: record.package },
+                    pageLanguage,
+                    pageOwner: key,
+                    ...(language ? { verbs: record.data?.grammar?.verbs } : {}),
+                    labelOf: (address) => byKey.get(address)?.name?.full,
+                    linkable: (ref) => {
+                        const target = byKey.get(renderAddress({ ...ref, system: "note" }));
+                        return Boolean(target && (target.address || hasLexicalEntries(target)));
+                    },
+                },
+            },
+        ]);
+    }
+    return sections;
+}
+
+/** Authored section headings outside literal content and named containers. */
+function headings(markdown) {
+    const containers = scanBlocks(markdown).blocks;
+    return scanHeadingAttributes(markdown)
+        .headings.filter(
+            (heading) =>
+                !containers.some(
+                    (block) => heading.line - 1 >= block.start && heading.line - 1 <= block.end,
+                ),
+        )
+        .map((heading) => ({ line: heading.line - 1, level: heading.level, slug: heading.id }));
+}
+
+/**
+ * Insert lists at the end of their authored anchored sections, or append a
+ * new H1 section when no heading names one. Source lines after an insertion
+ * retain their original positions; inserted lines point to their heading.
+ *
+ * @param {string} markdown - The body with authored directives expanded.
+ * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
+ * @param {{authored?: string, lineMap?: object[], generatedFrom?: number}} [context] -
+ *   The original authored body, source mappings and the start of appended
+ *   nonlexical generated sections. Without `authored`, `markdown` is the source.
+ * @returns {{markdown: string, lineMap: object[], generatedFrom?: number}}
+ */
+export function insertLexicalSections(
+    markdown,
+    sections = [],
+    { authored = markdown, lineMap, generatedFrom } = {},
+) {
+    const lines = String(markdown ?? "").split("\n");
+    const locations = lineMap ? [...lineMap] : lines.map((_, line) => ({ line, generated: false }));
+    if (!sections.length)
+        return {
+            markdown: lines.join("\n"),
+            lineMap: locations,
+            ...(generatedFrom === undefined ? {} : { generatedFrom }),
+        };
+    const edits = [];
+    const realHeadings = headings(String(authored ?? ""))
+        .map((heading) => ({
+            ...heading,
+            sourceLine: heading.line,
+            line: locations.findIndex(
+                (location, at) =>
+                    location.line === heading.line &&
+                    !location.generated &&
+                    (generatedFrom === undefined || at < generatedFrom),
+            ),
+        }))
+        .filter((heading) => heading.line >= 0);
+    for (const section of sections) {
+        const own = realHeadings.find((heading) => section.aliases.includes(heading.slug));
+        const next =
+            own &&
+            realHeadings.find((heading) => heading.line > own.line && heading.level <= own.level);
+        const at = next?.line ?? (own ? (generatedFrom ?? lines.length) : lines.length);
+        const level = own?.level ?? 1;
+        const render = section.slug === "dictionary" ? renderDictionary : renderGlossary;
+        const list = render(section.result, {
+            ...section.options,
+            sectionLevel: Math.min(6, level + 1),
+        });
+        if (!list && own) continue;
+        const text = `${own ? "" : `# ${section.heading} {#${section.slug}}\n\n`}${list}`;
+        edits.push({
+            at,
+            source: own?.sourceLine ?? Math.max(0, String(authored ?? "").split("\n").length - 1),
+            lines: ["", ...text.split("\n"), ""],
+        });
+    }
+    for (const edit of edits.sort((a, b) => b.at - a.at)) {
+        const location = { line: edit.source, generated: true };
+        lines.splice(edit.at, 0, ...edit.lines);
+        locations.splice(edit.at, 0, ...edit.lines.map(() => ({ ...location })));
+        if (generatedFrom !== undefined && edit.at <= generatedFrom)
+            generatedFrom += edit.lines.length;
+    }
+    return {
+        markdown: lines.join("\n"),
+        lineMap: locations,
+        ...(generatedFrom === undefined ? {} : { generatedFrom }),
+    };
+}

package/engine/markdownlint-run.mjs

@@ -41,6 +41,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { markupFindings } from "./markup-validation.mjs";
 
 import ignore from "ignore";
 import {
@@ -447,8 +448,9 @@ function gitignoreHooks(root) {
  *   `config`, `ignores`, `gitignore` and `globs`.
  * @param {boolean} [params.fix=false] - Repair what markdownlint can, then
  *   report what remains.
- * @returns {Promise<{results: object[]}>} markdownlint results, each with its
+ * @returns {Promise<{results: object[], markup: object[]}>} markdownlint results, each with its
  *   `fileName` relative to `directory`, ordered by file, line and rule.
+ *   `markup` carries block syntax diagnostics with absolute filenames.
  * @throws {MarkdownConfigError} A configuration file the contract refuses.
  */
 export async function runMarkdownlint(params) {
@@ -530,12 +532,20 @@ export async function runMarkdownlint(params) {
     };
 
     const resultsByFile = new Map();
+    const markup = [];
     for (const [dir, files] of groups) {
         const options = await lintOptions(dir, files);
+        const malformed = new Set();
+        for (const file of files) {
+            const findings = markupFindings(fs.readFileSync(file, "utf8"), file);
+            if (findings.length) malformed.add(file);
+            markup.push(...findings);
+        }
         let results = await lint(options);
         if (fix) {
             const toFix = [];
             for (const file of files) {
+                if (malformed.has(file)) continue;
                 const fixable = (results[file] ?? []).filter((error) => error.fixInfo);
                 if (!fixable.length) continue;
                 const original = fs.readFileSync(file, "utf8");
@@ -563,5 +573,5 @@ export async function runMarkdownlint(params) {
             a.ruleNames[0].localeCompare(b.ruleNames[0]) ||
             order.get(a) - order.get(b),
     );
-    return { results: flat };
+    return { results: flat, markup };
 }

package/engine/markup-validation.mjs

@@ -0,0 +1,34 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { scanBlocks } from "./content-blocks.mjs";
+import { scanAlerts } from "./content-alerts.mjs";
+
+/**
+ * Validate authored block syntax with positions in the original file.
+ * Frontmatter is masked so literal YAML values cannot become body markup.
+ * @param {string} source - Complete Markdown source, optionally with frontmatter.
+ * @param {string} file - Diagnostic filename.
+ * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
+ */
+export function markupFindings(source, file) {
+    const body = String(source ?? "").replace(
+        /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
+        (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
+    );
+    return [...scanBlocks(body).errors, ...scanAlerts(body).errors].map((error) => ({
+        file,
+        ...error,
+        severity: "error",
+    }));
+}

package/engine/note-addresses.mjs

@@ -41,6 +41,7 @@ export {
 
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES = Object.freeze([
+    { path: ["data", "seeAlso", "*", "address"], shape: "value", lenient: true },
     {
         path: ["packFolder"],
         shape: "scalar-or-map",

package/engine/note-claims.mjs

@@ -105,6 +105,7 @@ import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { BUNDLE_TYPE } from "./bundle-notes.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { hasLexicalEntries } from "./lexical-sections.mjs";
 
 /**
  * Note types that compile into **no compendium document, by design**.
@@ -666,11 +667,12 @@ function packsServing(config, docType, system) {
  * @param {string} absPath - The note's path, for the finding's position.
  * @param {string} type - The note's type.
  * @param {object} config - The resolved build configuration.
+ * @param {string} [raw] - Source text already read by the caller.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per
  *   discarded block.
  */
-function discardedSystemBlockFindings(fm, absPath, type, config) {
+function discardedSystemBlockFindings(fm, absPath, type, config, raw) {
     const findings = [];
     for (const system of SHIPPED_SYSTEMS) {
         if (!carriesSystemBlock(fm, system)) continue;
@@ -683,7 +685,7 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
         if (!packs || serving) continue;
         findings.push({
             file: absPath,
-            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true }),
+            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true, raw }),
             severity: /** @type {"error"} */ ("error"),
             type,
             message:
@@ -715,10 +717,16 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
  *   compile and handed in — required, for the reason above.
+ * @param {Map<string, {body: string, raw: string}>} [opts.parsed] - Already parsed
+ *   notes, keyed by file, for body checks and finding positions.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
-export function unclaimedNoteFindings(config = loadPackConfig(), sources, { records } = {}) {
+export function unclaimedNoteFindings(
+    config = loadPackConfig(),
+    sources,
+    { records, parsed } = {},
+) {
     const resolved = resolveSources(sources);
     const vocabulary = noteTypeVocabulary(resolved);
     const findings = [];
@@ -752,17 +760,20 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // Asked first, and asked whatever the type's claim turns out to be: a
         // note whose documents all have packs may still carry a block none of
         // them reads, and that is invisible to every question below.
-        findings.push(...discardedSystemBlockFindings(fm, absPath, type, config));
+        findings.push(
+            ...discardedSystemBlockFindings(fm, absPath, type, config, parsed?.get(absPath)?.raw),
+        );
 
         // Every document this note produces, against the classes this
         // configuration has a pack for. Three outcomes, and the middle one is
         // the half-claimed one — invisible while the question is only "is anything
         // claiming this note", because the answer there is yes.
         const produces = documentClassesFor(type, resolved, {
-            // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
-            // go asks, so a tree with a JournalEntry pack — which is most of
-            // them — reads no bodies at all.
-            hasProse: () => noteHasProse(absPath),
+            hasProse: () => {
+                if (hasLexicalEntries(fm)) return true;
+                const source = parsed?.get(absPath);
+                return source ? Boolean(source.body) : noteHasProse(absPath);
+            },
         });
         const missing = produces.filter((docType) => !configured.has(docType));
         const compiled = produces.filter((docType) => configured.has(docType));
@@ -791,7 +802,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         if (compiled.length) {
             findings.push({
                 file: absPath,
-                ...locateFrontmatterKey(absPath, "type", type),
+                ...locateFrontmatterKey(absPath, "type", type, { raw: parsed?.get(absPath)?.raw }),
                 severity: /** @type {"error"} */ ("error"),
                 type,
                 message: partialMessage(type, missing, compiled),
@@ -801,7 +812,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
 
         findings.push({
             file: absPath,
-            ...locateFrontmatterKey(absPath, "type", type),
+            ...locateFrontmatterKey(absPath, "type", type, { raw: parsed?.get(absPath)?.raw }),
             severity: /** @type {"error"} */ ("error"),
             type,
             message:

package/engine/note-package.mjs

@@ -62,12 +62,13 @@ export function searchableFrontmatter(fm, configured) {
  * @param {string} [options.absPath] - The note's file on disk, read only on the
  *   failing path to locate the offending line and column. The position rides on
  *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
  * @returns {void}
  * @throws {Error} When the note declares the field.
  */
-export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {}) {
+export function assertNoDeclaredPackage(fm, { file, absPath, configured, raw } = {}) {
     if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "package")) return;
 
     const target = configured ?? contentPackage();
@@ -84,10 +85,7 @@ export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {})
             `\`contentPackage\` ("${target}", in package-build.config.yaml), ` +
             `and every note in the tree belongs to it.`,
     );
-    // Where the field is, so the caller's diagnostic opens on the line that has
-    // to be deleted. Read here rather than carried through every walk: this is
-    // the failing path, and the build stops on it.
-    const position = locateFrontmatterKey(absPath, "package");
+    const position = locateFrontmatterKey(absPath, "package", undefined, { raw });
     if (position) err.position = position;
     throw err;
 }

package/engine/note-state.mjs

@@ -14,7 +14,7 @@
 /**
  * The three states of a note, and the one observable fact they rest on.
  *
- * A note whose body is empty is a **stub**: frontmatter only — identity and
+ * A note whose body is empty and has no automatic lexical content is a **stub**: frontmatter only — identity and
  * statistics — reaching the content index and queryable there, generating no
  * page, no address and no link target. A note with a body and the declared
  * `draft` tag is a **draft**: it publishes, compiles and resolves like any
@@ -39,6 +39,7 @@
  */
 
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { hasLexicalEntries } from "./lexical-sections.mjs";
 
 /**
  * The three states, in the order they read as a ladder.
@@ -97,7 +98,8 @@ export function isStubbableType(type, vocabulary = NOTE_VOCABULARY) {
 }
 
 /**
- * Whether a note is a stub: an empty body on a type an empty body suppresses.
+ * Whether a note is a stub: an empty body on a type an empty body suppresses,
+ * without an automatic dictionary or glossary supplied by its frontmatter.
  *
  * The one place the two halves are put together, so the index, the lint and the
  * guard cannot answer it differently.
@@ -109,7 +111,11 @@ export function isStubbableType(type, vocabulary = NOTE_VOCABULARY) {
  * @returns {boolean} Whether the note is a stub.
  */
 export function isStubNote(frontmatter, body, vocabulary = NOTE_VOCABULARY) {
-    return isEmptyBody(body) && isStubbableType(frontmatter?.type, vocabulary);
+    return (
+        isEmptyBody(body) &&
+        !hasLexicalEntries(frontmatter) &&
+        isStubbableType(frontmatter?.type, vocabulary)
+    );
 }
 
 /**

package/engine/note-vocabulary.mjs

@@ -72,6 +72,7 @@
  * @module
  */
 
+import { checkSeeAlso } from "./see-also.mjs";
 // The one charset, read rather than restated. A second spelling of the pattern
 // is how a disagreement between the three arises.
 import { ART_SLOTS } from "./art-slots.mjs";
@@ -203,7 +204,7 @@ import { checkSettlementTables } from "./settlement-tables.mjs";
  * @property {"pack"} [keys] - For a `scalar-or-map` field, what its keys name.
  *   `"pack"` means each is a pack this package declares, so a key naming none
  *   is a finding of its own: it addresses a hierarchy nothing will ever read.
- * @property {(note: object, opts: {index?: object}) => object[]} [check] - A
+ * @property {(note: object, opts: {index?: object, addressContext?: object}) => object[]} [check] - A
  *   check of the value beyond its shape, run by the frontmatter lint with the
  *   link index once the container has been checked. The lint stays
  *   vocabulary-agnostic this way: the rule lives beside the field that needs
@@ -599,7 +600,7 @@ const WORD_DATA_FIELDS = Object.freeze([
             fields: WORD_FIELDS,
         }),
         describe:
-            "The language's words, one map each, in the order they print. A language skill " +
+            "The words this language states, one map each, in authored order; its automatic dictionary sorts them alphabetically. A language skill " +
             "note only. See [a language's words](format-details.md#a-languages-words).",
     }),
     Object.freeze({
@@ -670,9 +671,10 @@ const GLOSSARY_FIELD = Object.freeze({
         fields: GLOSSARY_ENTRY_FIELDS,
     }),
     describe:
-        "Its own glossary terms: euphemisms, idioms, terms of art and titles that are not " +
-        "ranks. An entry with a `definition` creates a term or replaces its senses; one " +
-        "without marks a term the note already has. Every entry resolves to a language. " +
+        "Its own glossary entries: common vocabulary, dictionary words with a contextual " +
+        "meaning, and phrases, compounds or terms of art. A named dictionary word supplies " +
+        "its senses and class unless `definition` supplies the sense. Common marks belong " +
+        "to this owner. Every entry resolves to a language. " +
         "Empty when unstated. See [glossary terms](format-details.md#glossary-terms).",
 });
 
@@ -1001,6 +1003,33 @@ export const NOTE_TOP_LEVEL_KEY_SET = Object.freeze(new Set(NOTE_TOP_LEVEL_KEYS)
  * @type {readonly DataFieldSpec[]}
  */
 export const SHARED_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "seeAlso",
+        kind: "list",
+        shape: "list of `{ address, gloss? }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "`{ address, gloss? }`",
+            fields: Object.freeze([
+                Object.freeze({
+                    name: "address",
+                    kind: "address",
+                    shape: "a note Address",
+                    required: true,
+                    describe: "The note to read next.",
+                }),
+                Object.freeze({
+                    name: "gloss",
+                    kind: "string",
+                    shape: "a string",
+                    describe: "A short phrase saying why to follow the reference.",
+                }),
+            ]),
+        }),
+        check: checkSeeAlso,
+        describe:
+            "Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.",
+    }),
     Object.freeze({
         name: "id",
         ...TEXT,
@@ -1792,8 +1821,8 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...LANGUAGE_FIELD,
                 describe:
                     "The trade, temple or order tongue the affiliation keeps, as a language " +
-                    "skill note. It reaches the affiliation's culture, and its words enter that " +
-                    "culture's glossary. A glossary entry that states no `language` is in it.",
+                    "skill note. A glossary entry that states no `language` is in it. The " +
+                    "affiliation chooses its own common vocabulary and context meanings.",
             },
             GLOSSARY_FIELD,
             {

package/engine/pdf-build.mjs

@@ -120,6 +120,7 @@ import {
 import { artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs";
 import { embedRole } from "./content-embeds.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { seeAlsoEntries, seeAlsoMarkdown, seeAlsoWebLink } from "./see-also.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { eventNoteIndex } from "./event-fields.mjs";
 import { numberFigures, scanFigures } from "./content-figures.mjs";
@@ -1012,7 +1013,15 @@ async function prepareWorld(resolved, { contentBase, findings, resolveReplacemen
         scheme,
     };
     const collected = collectContentPages(contentBase, ctx);
-    const gates = siteGates(collected.pages, collected, { config: resolved, records });
+    const sqlTables = await prepareTreeSqlTables(contentBase, {
+        config: resolved,
+        skipDirectories: resolved.skipDirectories,
+        records,
+        parsed,
+        database: db,
+        audience: "public",
+    });
+    const gates = siteGates(collected.pages, collected, { config: resolved, records, sqlTables });
     if (gatesFailed(gates)) {
         for (const [name, list] of Object.entries(gates)) {
             if (!Array.isArray(list)) continue;
@@ -1029,14 +1038,6 @@ async function prepareWorld(resolved, { contentBase, findings, resolveReplacemen
 
     const byFile = new Map(collected.pages.map((page) => [page.file, page]));
     const universe = tableUniverse(collected.pages);
-    const sqlTables = await prepareTreeSqlTables(contentBase, {
-        config: resolved,
-        skipDirectories: resolved.skipDirectories,
-        records,
-        parsed,
-        database: db,
-        audience: "public",
-    });
     // The address space an `![[…]]` embed resolves against — the same one the
     // site builds, so one authored picture reaches both surfaces or neither.
     const assets = assetAddressIndex(records, {
@@ -1645,7 +1646,13 @@ async function buildBook(book, shared) {
         // Whether the entry is settled comes before anything it says: the
         // notice leads the leaf, before the authored body.
         const notice = isDraftNote(page.fm) ? draftNoticeTypst() : "";
-        const parts = [notice, prose, panel].filter((part) => part);
+        const references = seeAlsoMarkdown(
+            seeAlsoEntries(page.fm, (ref) => resolveInfoboxRef(gates.index, ref)),
+            seeAlsoWebLink,
+        );
+        const parts = [notice, prose, panel, references ? typst(references, {}) : ""].filter(
+            (part) => part,
+        );
         return parts.join("\n\n");
     };