@heroiclands/package-build 25.1.3 → 25.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @heroiclands/package-build
 
+## 25.2.0
+
+**Content and notes**
+
+- A note lists its other names under the code of their language, beside the English `full`: `name: {full: Johnathan Lewis, en: [John], vyla: [juan juis]}`.
+- A note states its language as `data.lang`, a code `languages:` declares or `en`; a note that states none takes its culture's, then its parents', then `en`.
+- A culture that states no language, and inherits none from a parent culture, is an error wherever a note names it.
+- Names match whatever their case, so `[arden vale]{.name}` names the note _Arden Vale_.
+- A `.name` span can carry `ref=` to tie each spelling of a person, place or thing to its note without linking it: `[Tom]{.name ref=being-tomr}`.
+- A `ref` may be a page-local key such as `ref="#jane"` for a subject with no note, and a `ref` that matches no note is an error.
+
+**Rendering and sites**
+
+- The first use of each name in a page is bold on the website, in Foundry journals and in the book, and its later uses are plain text.
+- Every spelling tied by one `ref`, every link to one note and every case of one label count as one name.
+- A wikilink counts as a name when it carries `.name`, such as `[[place-harbor|the harbor]]{.name}`; names in headings, tables, captions and other-language runs take no bold.
+
+**Builds and commands**
+
+- `changelog check` now refuses a changeset that is not labelled blocks of bullets: a lead paragraph, an unlabelled bullet, prose between blocks and a label that is not declared are errors.
+- A label must be in `labels` or be `Miscellaneous`, which every repository has and never declares; with no list declared, only `Miscellaneous` is accepted.
+- `changelog check --release` holds a Version Packages section to the same shape.
+- `changelog group` removes the `### … Changes` headings, merges blocks that share a label, orders them as `labels` declares and lists `Miscellaneous` last.
+
+**Upgrading**
+
+- Declare `labels` in the changelog options of `.changeset/config.json`, and rewrite pending changesets as labelled blocks of bullets before upgrading.
+- Move each `aliases` entry under its language's code, or `en`, and write `data.lang: <code>` in place of `data.language: skill-…`; both old keys are refused.
+
 ## 25.1.3
 
 **Spelling checks**

package/assets/styles/content-base.css

@@ -584,15 +584,6 @@
     outline-offset: 2px;
 }
 
-/*
- * A name the text marks is bold, as on the site, in the preview and in the book.
- * Foundry's interface and a system's sheets use `.name` for their own elements,
- * which the content roots leave untouched.
- */
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .name {
-    font-weight: var(--pb-name-weight, 700);
-}
-
 /*
  * A wikilink whose target no package publishes keeps its text and is marked, so
  * the sentence still reads and a reader can tell a link was meant. Each value

package/bin/content-commands.mjs

@@ -139,6 +139,7 @@ import { stagePackageBuildAssets } from "../engine/build-assets.mjs";
 import { DEPLOYED_ASSET_TYPES } from "../engine/asset-types.mjs";
 import { createContentSession, CONTENT_TARGETS } from "../engine/content-session.mjs";
 import { createFirstUseChecker } from "../engine/first-use.mjs";
+import { createNameRefChecker } from "../engine/name-refs.mjs";
 import { createNameCatalog, createNamesReport, namesReportFinding } from "../engine/names.mjs";
 // The one place a link finding is worded, shared with both builds.
 import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
@@ -1037,6 +1038,11 @@ function lintCommand() {
                     syntax: session.syntax,
                     catalog,
                 });
+                const nameRefChecker = createNameRefChecker({
+                    catalog,
+                    parsed: session.parsed,
+                    syntax: session.syntax,
+                });
                 const names = namesReportFinding(
                     createNamesReport({ package: config.contentPackage, records, catalog }),
                     { contentBase: root },
@@ -1075,6 +1081,8 @@ function lintCommand() {
                 }
                 const frontmatter = lintFrontmatter(index, {
                     currentDate: config.currentDate,
+                    // The codes a note's `name` lists its forms under.
+                    languages: Object.keys(config.languages ?? {}),
                     schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
                     // The closed frontmatter regions. Passed in rather
                     // than reached for, so the linter stays a checker of
@@ -1300,6 +1308,7 @@ function lintCommand() {
                     ...(runs.encodingFindings ?? []),
                     ...languageNoteFindings({ ...config, configFile: packConfigPath() }, records),
                     ...index.notes.flatMap(firstUseChecker),
+                    ...index.notes.flatMap(nameRefChecker),
                     ...(names ? [names] : []),
                     ...addresses.findings,
                     ...frontmatter.findings,
@@ -3400,16 +3409,16 @@ function newNpc(config, argv) {
         throw new Error(`${key}'s appearance profile has ${profileErrors.length} problem(s)`);
     }
 
-    const tongue = culture.data?.language;
-    if (tongue === undefined || tongue === null)
+    const code = hit.lang;
+    const tongue = typeof code === "string" ? config.languages?.[code]?.note : undefined;
+    if (tongue === undefined)
         throw noteError(
             cultureNote,
-            ["data"],
-            `${key} states no \`data.language\`, so \`npc new\` has no name lists to draw ` +
-                "from; name the language skill note its people speak",
+            Object.hasOwn(culture.data ?? {}, "lang") ? ["data", "lang"] : ["data"],
+            `${key} is in ${code ?? "no language"}, which \`languages:\` names no language ` +
+                "note for, so `npc new` has no name lists to draw from; state the culture's " +
+                "`data.lang` and its language's `note`",
         );
-    const languageSource = cultureFieldSource(records, key, "language") ?? hit;
-    const languageSourceNote = located(languageSource);
     const tuple = parseAddress(tongue, {
         package: index.contentPackage,
         system: "note",
@@ -3420,18 +3429,15 @@ function newNpc(config, argv) {
     const languageKey = tuple.reason ? undefined : renderAddress(tuple);
     const languageHit = languageKey ? index.addressHit(languageKey) : undefined;
     if (!languageHit)
-        throw noteError(
-            languageSourceNote,
-            ["data", "language"],
-            `${key}'s \`data.language\` names no note in this package or its dependencies`,
+        throw new Error(
+            `\`languages.${code}.note\` ${tongue}, ${key}'s language, names no note in this ` +
+                "package or its dependencies",
         );
     const language = languageHit.fm ?? languageHit;
     if (String(language.type ?? languageHit.type) !== "skill" || language.subType !== "language")
-        throw noteError(
-            languageSourceNote,
-            ["data", "language"],
-            `${key}'s \`data.language\` ${languageKey} is not a language: it names a ` +
-                `${language.type ?? languageHit.type ?? "note"} of subType ` +
+        throw new Error(
+            `\`languages.${code}.note\` ${languageKey}, ${key}'s language, is not a language: ` +
+                `it names a ${language.type ?? languageHit.type ?? "note"} of subType ` +
                 `${language.subType ?? "none"}`,
         );
     const languageNote = located(languageHit);

package/bin/package-build.mjs

@@ -92,7 +92,7 @@ import { emitDiagnostic, formatDiagnostic } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments, siteBase } from "../content-config.mjs";
-import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
+import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, resetStage } from "../stage.mjs";
 import {
     CDN_ENV,
@@ -115,6 +115,7 @@ import { validateLangSource } from "../lang.mjs";
 import { lintYaml } from "../engine/yaml-lint.mjs";
 import { lintChangesetText, lintReleaseText } from "../engine/changelog-lint.mjs";
 import { groupChangelogText } from "../engine/changelog-group.mjs";
+import { readChangelogLabels } from "../engine/changelog-labels.mjs";
 import { bumpDependencies } from "../engine/dependency-bump.mjs";
 import {
     analyzeCoverage,
@@ -1066,35 +1067,33 @@ function yamlCommand() {
 }
 
 /**
- * `changelog check` / `changelog group` — release-prose checks, and folding
- * a release's changeset blocks together by their bold label.
- *
- * `check` answers one question a changeset otherwise goes unheld to — who
- * notices, and what do they see — so a pull-request description pasted into
- * one does not ship verbatim as a release note. Default reads every pending
- * changeset; `--release` reads the first `## <version>` section of
- * `CHANGELOG.md` instead, for the **Version Packages** branch a merge to
- * `main` opens.
- *
- * `group` rewrites that same first `## <version>` section in place: every
- * changeset in it writes its own `**Compendiums**` block, and nothing merges
- * the three a release with three compendium fixes ends up with. It reads
- * `changelog.labels` for the vocabulary and display order, when the
- * repository declares one.
+ * `changelog check` / `changelog group` — the changeset shape check, and the
+ * final grouping of a release.
+ *
+ * `check` holds a changeset to the house shape — labelled blocks of
+ * bullets, labels from `.changeset/config.json` or `Miscellaneous` — and to the
+ * rules that keep a pull-request description out of a release note. Default
+ * reads every pending changeset; `--release` reads the first `## <version>`
+ * section of `CHANGELOG.md` instead, for the **Version Packages** branch a
+ * merge to `main` opens.
+ *
+ * `group` rewrites that same first `## <version>` section in place: it removes
+ * the `### … Changes` headings, merges blocks sharing a label and orders them
+ * as the labels in `.changeset/config.json` declare, `Miscellaneous` last.
  *
  * @returns {object} The yargs command module.
  */
 function changelogCommand() {
     return {
         command: "changelog <action> [paths..]",
-        describe: "Release-prose checks, and folding a release's blocks by label",
+        describe: "Check changesets against the house shape, and group a release's blocks by label",
         builder: (y) =>
             y
                 .positional("action", {
                     choices: ["check", "group"],
                     describe:
                         "check: lint pending changesets, or a release section. " +
-                        "group: fold a release section's blocks together by label",
+                        "group: give the newest release its final shape",
                 })
                 .positional("paths", {
                     describe:
@@ -1135,17 +1134,17 @@ function changelogFiles(args) {
 }
 
 /**
- * `changelog.labels`, when this repository declares a configuration — `null`
- * otherwise, so `check` and `group` both work in a tree with no
- * `package-build.config.yaml` at all, exactly as `check` already does for
- * pending changesets with no configuration to read.
+ * The labels in `.changeset/config.json`, or `null` when it declares none.
+ * An invalid declaration stops the command.
  *
  * @returns {readonly string[]|null}
  */
 function loadChangelogLabels() {
-    const found = resolveConfigFile();
-    if (!found.path) return null;
-    return loadPackConfig().changelog.labels;
+    try {
+        return readChangelogLabels();
+    } catch (error) {
+        return die(`changelog: ${error.message}`);
+    }
 }
 
 /**

package/content-config.mjs

@@ -71,6 +71,7 @@ import { normalizeCurrentDate } from "./engine/current-date.mjs";
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
 import { isLanguageTag } from "./engine/language-tag.mjs";
+import { NAME_STRING_KEYS } from "./engine/name-forms.mjs";
 import { ASSET_TYPE_NAMES, shippingLicensesProblem } from "./engine/asset-types.mjs";
 import { isReservedPackage } from "./engine/packages.mjs";
 import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
@@ -764,12 +765,10 @@ const CONFIG_KEYS = [
     "requiresSystem",
     "packageBuild",
     "publish",
-    "changelog",
 ];
 const SYSTEM_KEYS = ["manifest", "compatibility"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
-const CHANGELOG_KEYS = ["labels"];
 const SITE_KEYS = [
     "base",
     "title",
@@ -983,6 +982,12 @@ function normalizeLanguages(value) {
                 "is not a name: a name is lowercase letters, digits and single hyphens, " +
                     "starting with a letter",
             );
+        if (NAME_STRING_KEYS.includes(name))
+            fail(
+                where,
+                `is a \`name\` key that holds a single string (${NAME_STRING_KEYS.join(", ")}), ` +
+                    "so a note's forms cannot be listed under it; choose another name",
+            );
         if (!isPlainObject(entry)) fail(where, "must be a mapping with `tag`");
         rejectUnknownKeys(entry, ["tag", "note"], `${where}.`);
         const { tag, note } = /** @type {Record<string, unknown>} */ (entry);
@@ -1627,37 +1632,6 @@ function normalizeDocs(value) {
     });
 }
 
-/**
- * `changelog.labels` — the vocabulary and display order `changelog check`
- * and `changelog group` read a release block's bold label against.
- *
- * Optional: a repository that groups nothing declares none, and `group`
- * falls back to ordering every label by first appearance. Declared, it is a
- * list of non-empty strings with no duplicate — a repeated label could never
- * be told apart from a genuine drift (`Compendiums` twice would silently
- * swallow the `Character data` beside `Characters` the list exists to catch).
- *
- * @param {unknown} value - The configured value, or `undefined`.
- * @returns {Readonly<{labels: readonly string[]|null}>}
- */
-function normalizeChangelog(value) {
-    if (value === undefined) return Object.freeze({ labels: null });
-    if (!isPlainObject(value)) fail("changelog", "must be a mapping");
-    const input = /** @type {Record<string, unknown>} */ (value);
-    rejectUnknownKeys(input, CHANGELOG_KEYS, "changelog.");
-    if (input.labels === undefined) return Object.freeze({ labels: null });
-    if (!Array.isArray(input.labels)) fail("changelog.labels", "must be an array");
-    const labels = input.labels.map((label, index) =>
-        requireNonEmptyString(label, `changelog.labels[${index}]`),
-    );
-    const seen = new Set();
-    for (const label of labels) {
-        if (seen.has(label)) fail("changelog.labels", `declares \`${label}\` more than once`);
-        seen.add(label);
-    }
-    return Object.freeze({ labels: Object.freeze(labels) });
-}
-
 /**
  * The asset host the website resolves a pathname against.
  *
@@ -3228,6 +3202,5 @@ export function defineConfig(config) {
         requiresSystem,
         packageBuild: normalizePackageBuild(input.packageBuild),
         publish: normalizePublish(input.publish),
-        changelog: normalizeChangelog(input.changelog),
     });
 }

package/docs/api.md

@@ -989,24 +989,40 @@ content and asset scopes preserve their own filtering and order.
 
 Import from `@heroiclands/package-build/engine/first-use`.
 
-| Export                  | Signature                                                               | Returns                  | Use it when                                                                    |
-| ----------------------- | ----------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------ |
-| `createFirstUseChecker` | `createFirstUseChecker({ records, index, catalog?, parsed?, syntax? })` | `checker({ file, raw })` | Checking authored prose against the current corpus's name-marking conventions. |
+| Export                  | Signature                                                               | Returns                  | Use it when                                                                        |
+| ----------------------- | ----------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
+| `nameUses`              | `nameUses(markdown, vocabulary?)`                                       | `NameUse[]`              | Listing the uses of names a body's prose makes, each with the key it counts under. |
+| `boldFirstUses`         | `boldFirstUses(markdown, vocabulary?)`                                  | `string`                 | Marking the first use of each key in a body's prose before a target renders it.    |
+| `firstUsePlugin`        | `md.use(firstUsePlugin)`                                                | —                        | Rendering the marks as strong text in a markdown-it parser.                        |
+| `FIRST_USE_OPEN`        | constant                                                                | `"\uFDD0"`               | Recognizing where a first use opens in expanded markdown.                          |
+| `FIRST_USE_CLOSE`       | constant                                                                | `"\uFDD1"`               | Recognizing where a first use closes in expanded markdown.                         |
+| `createFirstUseChecker` | `createFirstUseChecker({ records, index, catalog?, parsed?, syntax? })` | `checker({ file, raw })` | Checking a note's marked names against the index.                                  |
+
+A `NameUse` is `{start, end, key, emphasised}`: the use's UTF-16 range in the
+markdown, the key it counts under, and whether it sits inside authored strong
+text. The key is a name wikilink's address, a span's `ref`, or the span's
+case-folded label with its `lang`. `vocabulary` is `{types, packages,
+noIndexPackages, contentPackage}`, which reads every spelling of an address as
+one note; without it an address is keyed as written. Only prose counts:
+headings, tables, captions, raw HTML, code, verse and runs that state `lang`,
+`font` or `enc` neither take the bold nor count. `boldFirstUses` wraps each
+first use in the two marks, except one already inside authored strong text,
+and `firstUsePlugin` turns each mark in inline text into a `strong` token and
+drops a mark anywhere else. `expandContent` runs `boldFirstUses` on the
+author's prose for every target, and `createRenderer` installs the plugin on
+every target.
 
 Construct one checker with the session's read-only `records` and
 `await session.audit("lint")`. Call it for each existing link-index note.
 It performs no I/O and returns `{file, line, column, severity: "warning",
-rules, message}` diagnostics. `rules` is a list of applicable rule names, merged
-into one warning for each occurrence; the message names the full name or
-explicit label that needs attention. Only `.name` spans and authored link
-labels enter name tracking; plain text is not searched. Indexed full names and
-declared aliases share an identity, while other labels use their whole text.
-Local and captured dependency names and aliases share the same corpus
-context. The command's lint target constructs
-the checker once, uses exact authored `raw` strings and keeps these findings
+rules, message}` diagnostics. `rules` is a list of applicable rule names,
+merged into one warning for each occurrence: `unlinked-name` for a `.name`
+span without `ref` whose label is an indexed full name or listed form. Plain
+text is not searched. The command's lint target constructs the
+checker once, uses exact authored `raw` strings and keeps these findings
 advisory. See the [authoring conventions](authoring/links-and-markup.md#marking-names-in-prose).
 
-Supply the invocation's `catalog` to share its full-name and alias lookup with
+Supply the invocation's `catalog` to share its full-name and form lookup with
 the package names report. Optional `parsed` maps absolute files to captured
 `{raw, body, bodyLine?, bodyColumn?}`; `syntax` is the session's scanner
 projection. When the captured raw text matches, the checker rebases the body's
@@ -1050,7 +1066,7 @@ Import from `@heroiclands/package-build/engine/name-rows`.
 
 | Export         | Signature            | Returns                     | Use it when                                                            |
 | -------------- | -------------------- | --------------------------- | ---------------------------------------------------------------------- |
-| `NAME_COLUMNS` | `const NAME_COLUMNS` | Frozen ordered column names | Reading `owner`, `name`, `type`, `subType`, `line`, `column`.          |
+| `NAME_COLUMNS` | `const NAME_COLUMNS` | Frozen ordered column names | Reading `owner`, `name`, `type`, `subType`, `ref`, `line`, `column`.   |
 | `namesRows`    | `namesRows(records)` | `NameRow[]`                 | Projecting own-note occurrences into SQL rows without I/O or mutation. |
 
 Rows preserve record and occurrence order. `owner` is the canonical NOTE page
@@ -1067,7 +1083,8 @@ Import from `@heroiclands/package-build/engine/names`.
 
 | Export                  | Signature                                                      | Returns                           | Use it when                                                                                  |
 | ----------------------- | -------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- |
-| `normalizeName`         | `normalizeName(text)`                                          | `string`                          | Normalizing NFC, apostrophes and whitespace while preserving case.                           |
+| `normalizeName`         | `normalizeName(text)`                                          | `string`                          | Normalizing NFC, apostrophes and whitespace and folding case, as names are matched.          |
+| `displayName`           | `displayName(text)`                                            | `string`                          | Normalizing NFC, apostrophes and whitespace while keeping case, as names are displayed.      |
 | `nameForms`             | `nameForms(text)`                                              | `string[]`                        | Enumerating supported whole-label possessives and regular plurals.                           |
 | `createNameCatalog`     | `createNameCatalog({ records, index })`                        | `NameCatalog`                     | Sharing indexed full-name, alias and resolved Address matching across checks.                |
 | `collectUnwrittenNames` | `collectUnwrittenNames({ records, catalog })`                  | `{groups, firstUse}`              | Grouping every unresolved captured occurrence by supplied classification.                    |
@@ -1102,8 +1119,8 @@ at the earliest reported actual use, and returns no warning for an empty report.
 Collecting and publishing this package's content index. Records describe note frontmatter, assets, prose and event anchors, and the document targets those notes produce. Dynamic publication prepares the same generated Markdown and scalar expressions as the rendering surfaces, using each source note's audience.
 
 Own-note records carry derived `names` entries in source order as
-`{name, type, subType, line, column}`. Missing classifications are explicit
-`null`; no occurrences gives `[]`. Positions refer to original authored span
+`{name, type, subType, ref, line, column}`. Missing classifications and an
+absent `ref` are explicit `null`; no occurrences gives `[]`. Positions refer to original authored span
 openings, before generated content. Metadata JSONL transports these entries
 to dependency SQL without an additional artifact. This field is reserved for
 derived data, and is not an authored frontmatter key.
@@ -1120,7 +1137,7 @@ configuration's `itemTypes`.
 | `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                                                                                         | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well. | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                                                                                                                          |
 | `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                                                                              | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                      | Recursively sort an object's keys, so serialization is order-independent.                                                                                                                                                                                                           |
 | `asciiName`             | `function asciiName(name)`                                                                                                                                  | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                           | A note's display name reduced to printable 7-bit ASCII.                                                                                                                                                                                                                             |
-| `asciiAliases`          | `function asciiAliases(aliases)`                                                                                                                            | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                    | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                                                                                                                                 |
+| `asciiForms`            | `function asciiForms(name)`                                                                                                                                 | {Record<string, string[]>} Possibly empty, never null: a note listing no form has an empty map, which a consumer iterating it need not check first.                                                                      | A note's listed name forms reduced to printable 7-bit ASCII, by language.                                                                                                                                                                                                           |
 | `serializeContentIndex` | `function serializeContentIndex(records)`                                                                                                                   | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                           | Serialize records as JSON Lines.                                                                                                                                                                                                                                                    |
 | `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems, parsed, sources, syntax, foreignIndex, nameTypes? })`                                    | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                        | The index records for a content tree, without writing anything.                                                                                                                                                                                                                     |
 | `indexRecordsForNote`   | `indexRecordsForNote({ frontmatter, body, bodyLine, bodyColumn?, nameTypes?, relPath, absPath, raw, contentPackage, manifest, addressContext })`            | `object[]`                                                                                                                                                                                                               | Derive the note's own record and its documentation record from parsed text.                                                                                                                                                                                                         |
@@ -1181,8 +1198,8 @@ scalar expressions, events or other generated sections require
 `indexRecordsFor` and `collectContentIndex` collect authored records and pure
 lexical sections; use preparation and emission to publish dynamic body targets.
 
-On lore and affiliation notes, `data.language` and `data.glossary[].language`
-require a language NOTE Address. Decoding refuses other recognized system
+On lore and affiliation notes, `data.glossary[].language` requires a
+language NOTE Address. Decoding refuses other recognized system
 segments at the authored value, naming the complete
 `<pkg>-note-skill-<shortcode>` to write. A short local form such as
 `skill-provnzlng` is also accepted. See the [glossary language
@@ -2494,8 +2511,8 @@ focusable inline spoiler: scoped content CSS redacts its text and descendants
 until pointer hover or keyboard focus reveals them. Its focus outline and
 accessible cue identify the reveal interaction. Native Foundry secret sections
 keep their separate controls. Book rendering discards inline `.secret` classes
-and prints their content normally, retaining emphasis, links, anchors and `.name`
-bold styling. Book secret sections and fences retain their visible labelled
+and prints their content normally, retaining emphasis, links, anchors and a
+name's first-use bold. Book secret sections and fences retain their visible labelled
 boxes. The span parser's opaque source tokens retain a `secret` boolean from
 their parsed classes for preview presentation.
 `collectAnchors` includes `secret: true` on secret anchors for destination

package/docs/authoring/first-note.md

@@ -41,9 +41,9 @@ For optional writing suggestions, run `npx package-build prose lint assets/conte
 
 The full Address is `<package>-note-lore-harbor`; `<package>` comes from `contentPackage` in `package-build.config.yaml`. In another note, `[[lore-harbor|Harbor]]` links to it. `[[lore-harbor|]]` asks the renderer to use the target's current name. The pipe is required.
 
-Use another subject's full canonical name at its first prose mention, then
-plain text for later mentions and aliases. Keep a note's own subject in plain
-text. Link indexed subjects even when they are private: the destination's
+Mark another subject's name with a link or a `.name` span; its first use in
+the page is bold when it renders. Keep a note's own
+subject in plain text. Link indexed subjects even when they are private: the destination's
 audience automatically makes the whole reference a spoiler. Add `.show` only
 to intentionally reveal the reference; it grants no access to the destination.
 For an unwritten subject, use a typed span such as

package/docs/authoring/frontmatter.md

@@ -12,7 +12,7 @@ HeroicLands notes begin with YAML frontmatter. A file is recognized as a note wh
 ```yaml
 ---
 shortcode: harbor
-name: { full: Harbor, aliases: [The Harbor] }
+name: { full: Harbor, en: [The Harbor] }
 type: lore
 subType: economy
 description: A sheltered trading port.
@@ -21,7 +21,35 @@ data: {}
 ---
 ```
 
-`name` is a map with a required, nonempty `full` display name. Every note may also use `aliases` for an ordered list of other names, and `sort` for the form the name takes in an index, such as `Black Flame, The` or `Hilvan, Doran`. The note infobox lists aliases directly beneath the full name. `sort` files the note wherever notes are ordered by name — the book index, page lists, generated lists of related notes, and the `nameSort` column of the `entries` relation — and is the note's entry text in the book index. Every other list still displays the `full` name. A note with no `sort` files and indexes by its `full` name. For `name: {full: The Black Flame, sort: "Black Flame, The"}`, the book index prints _Black Flame, The_ under **B**, and a page list prints _The Black Flame_ at the same place.
+`name` is a map with a required, nonempty `full` display name: the English name a page, a compendium entry and an index print. Every other name the subject goes by is listed under the code of its language, a code [`languages:`](../configuration.md#languages) declares, or `en`, which needs no declaration. `full` already counts as an English form, so `en` lists only the other English names and never repeats `full`. The first form in each list is that language's standard form. Any other key under `name` is an error at its line. The note infobox lists every form directly beneath the full name.
+
+`sort` gives the form the name takes in an index, such as `Black Flame, The` or `Hilvan, Doran`. `sort` files the note wherever notes are ordered by name — the book index, page lists, generated lists of related notes, and the `nameSort` column of the `entries` relation — and is the note's entry text in the book index. Every other list still displays the `full` name. A note with no `sort` files and indexes by its `full` name. For `name: {full: The Black Flame, sort: "Black Flame, The"}`, the book index prints _Black Flame, The_ under **B**, and a page list prints _The Black Flame_ at the same place.
+
+A person with nicknames lists them in the language they are said in:
+
+```yaml
+name: { full: Johnathan Lewis, en: [John, Long John], vyla: [juan juis] }
+```
+
+A people with a name of its own gives its English name as `full` and its own name first under its language. Another people's name for it, an exonym, goes under that people's language:
+
+```yaml
+name: { full: Grass People, tenl: [tenlaya], kiic: [kitchek] }
+```
+
+Names match whatever their case: `Harbor`, `harbor` and `HARBOR` all name the note above, and every form is matched the same way. Display keeps the case the note writes. Two notes whose forms differ only by case are one ambiguous name, reported wherever the name is used.
+
+`data.lang` states the language the note is in, as a code `languages:` declares or `en`. Any note may state it. A note that does not takes its language from its `data.culture`'s language, then from its `data.parents`, nearest first, then `en`; see [a note's language](../reference/format-details.md#a-notes-language). A culture note's language is how the notes of its people find their tongue:
+
+```yaml
+---
+shortcode: grassfolk
+name: { full: Grass People, tenl: [tenlaya] }
+type: lore
+subType: culture
+data: { lang: tenl }
+---
+```
 
 `description` is the short page summary. `tags` hold draft state and descriptive labels. The note type's classification belongs in `subType` where it is declared. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.