@heroiclands/package-build 23.12.6 → 23.12.8

package/docs/commands.md

@@ -350,9 +350,16 @@ the shipping list (the default list plus `packageBuild.shippingLicenses`) is cop
 at the package root, through the same transform, and the package's asset set,
 `asset-sets/default.json`, lists what was staged. Everything else stays in the repository. See
 [what a package ships](reference/format-details.md#what-a-package-ships).
-A `packageBuild.assets` row that copies a picture root, a directory inside
-one, or a directory holding one is refused, because it would ship every file
-unfiltered.
+
+The pictures are written beside whatever a `packageBuild.assets` row copied
+into `icons/` or `images/`, and nothing there is removed. A picture whose
+deployed path is already a file a row staged is an error, and no picture is
+staged:
+
+> ``build/stage/images/gate.png: error: `images/gate.png` is already in the stage, copied by a `packageBuild.assets` row; the picture `assets/images/places/gate.png` was not staged over it``
+> A `packageBuild.assets` row that copies a picture root, a directory inside
+> one, or a directory holding one is refused, because it would ship every file
+> unfiltered.
 
 **OPTIONS**
 
@@ -2485,6 +2492,12 @@ with visible text, nullable type/subtype and original source line/column.
 Local and dependency SQL schemas expose them through `names`; they travel in
 the metadata artifact.
 
+Metadata also includes each own note's spans, divs and poetry fences marked with
+`lang=`, `font=` or `map=` under `runs`, with the language as written, the tag
+it resolves to, the font, the map and the original source line/column. Local
+and dependency SQL schemas expose them through `runs`, and each mapping note's
+rows through `maps`.
+
 The command prepares SQL tables, page lists, automatic sections and scalar
 expressions before publishing their prose targets. Each source uses its own
 audience for prose declarations: public notes use public providers and usage,
@@ -2970,6 +2983,127 @@ $ package-build reachability assets/content
 `package-build links [root]`, `package-build lint [root]`, [Diagnostics](diagnostics.md),
 [Configuration](configuration.md).
 
+### `package-build transliterate <map> [text..]`
+
+**NAME**
+
+Map a passage into a script exactly as the build maps a marked run.
+
+**SYNOPSIS**
+
+```
+package-build transliterate <map> [--lang <language>] [--font <slug>] [--hex] [text..]
+```
+
+**DESCRIPTION**
+
+Reads the content index, as `package-build lint` does, and prints the passage
+rewritten by the mapping note whose `data.map.name` is `<map>`, through the
+same code the build sets a run marked `map=<map> lang=<language> font=<slug>`
+with. With `--lang`, each word the language's lexicon states a native form for
+is written by it and every other word is spelled by the rows; without it, the
+rows alone apply. See
+[a map reads the dictionary first](reference/format-details.md#a-map-reads-the-dictionary-first).
+The text is the words given, joined by single spaces; `-` or no text reads it
+from standard input, less one trailing newline. Writes nothing.
+
+**OPTIONS**
+
+| Positional | Type             | Default | Description                            |
+| ---------- | ---------------- | ------- | -------------------------------------- |
+| `map`      | string           | —       | The `data.map.name` of a mapping note. |
+| `text`     | string, variadic | stdin   | The passage; `-` reads it from stdin.  |
+
+| Option   | Type    | Default                    | Description                                                                     |
+| -------- | ------- | -------------------------- | ------------------------------------------------------------------------------- |
+| `--lang` | string  | —                          | A language declared in `languages`, whose lexicon is read first.                |
+| `--font` | string  | the map's one face, if one | The face, whose own rows come first; required when the map lists more than one. |
+| `--hex`  | boolean | `false`                    | Print the code points, as `U+XXXX` separated by spaces.                         |
+
+**EXIT STATUS**
+
+1 if the content index could not be built for any note, or the map, the
+language or the face names nothing, each reported as a finding: an unknown
+language at `languages` in the configuration, an unknown map or face at the
+content tree. 1, with the build's own message, if a capitalised word of the
+passage has a native form the rows cannot capitalise. Otherwise 0.
+
+**EXAMPLES**
+
+With Vylari's `zaron` stating a native form for `semaron`, and `lonak` stating
+none:
+
+```
+$ package-build transliterate semaron --lang vyl --hex zaron lonak
+U+F024F U+F0230 U+F023F U+F023C U+0020 U+F023A U+F023D U+F023C U+F0230 U+F0239
+$ package-build transliterate semaron --hex zaron
+U+F0255 U+F0230 U+F023F U+F023D U+F023C
+$ package-build transliterate semoran zaron
+assets/content: error: `semoran` is not a map: a map is named by the `data.map.name` of a mapping note; did you mean `semaron`?
+```
+
+The first run writes `zaron` by its exception; the second, with no `--lang`,
+spells it by the rows.
+
+**SEE ALSO**
+
+`package-build lexicon <language>`, [Mapping notes](reference/format-details.md#mapping-notes).
+
+### `package-build lexicon <language>`
+
+**NAME**
+
+List a language's words with their native forms under a map.
+
+**SYNOPSIS**
+
+```
+package-build lexicon <language> --map <map> [--font <slug>] [--json]
+```
+
+**DESCRIPTION**
+
+Reads the content index and lists every word of the language note
+[`languages.<language>.note`](configuration.md#languages) names, in `data.words`
+order, each with its native form under `<map>`: the stated exception where the
+word has one, else the rows' spelling, each exactly as
+`package-build transliterate` and the build give it. Each line holds, separated
+by tabs, the word's `form`, its native form, `exception` or `rows`, its `class`
+and its `gloss`. Writes nothing.
+
+**OPTIONS**
+
+| Positional | Type   | Default | Description                                         |
+| ---------- | ------ | ------- | --------------------------------------------------- |
+| `language` | string | —       | A declared language whose `note` names its lexicon. |
+
+| Option   | Type    | Default                    | Description                                                                |
+| -------- | ------- | -------------------------- | -------------------------------------------------------------------------- |
+| `--map`  | string  | —                          | Required: the `data.map.name` of a mapping note.                           |
+| `--font` | string  | the map's one face, if one | The face; required when the map lists more than one.                       |
+| `--json` | boolean | `false`                    | Print a JSON array of `{ form, native, exception, class, gloss }` instead. |
+
+**EXIT STATUS**
+
+1 if the content index could not be built for any note, or the language, the
+map or the face names nothing, the language states no `note`, or a capitalised
+word has a native form the rows cannot capitalise, each reported as a finding.
+Otherwise 0.
+
+**EXAMPLES**
+
+```
+$ package-build lexicon vyl --map semaron | head -3
+zaron	<native form>	exception	n	an oath
+lonak	<native form>	rows	n	a road
+thizaron	<native form>	rows	n	a seal
+```
+
+**SEE ALSO**
+
+`package-build transliterate <map> [text..]`,
+[A language's words](reference/format-details.md#a-languages-words).
+
 ### `package-build addresses diff`
 
 **NAME**

package/docs/configuration.md

@@ -54,7 +54,7 @@ around its own evaluation.
 
 ### Quick reference
 
-25 top-level keys. `rootDir` is not one of them — a data configuration never
+26 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -75,6 +75,7 @@ authoring.
 | [`skipDirectories`](#skipdirectories)       | string[]                                                                   | no                                                                                                 | `[]`                      |
 | [`forbidGeneratedArt`](#forbidgeneratedart) | boolean                                                                    | no                                                                                                 | `false`                   |
 | [`icons`](#icons)                           | object, or a path to a file holding one                                    | no                                                                                                 | empty registry            |
+| [`languages`](#languages)                   | object (name → `{tag, note?}`)                                             | no                                                                                                 | `{}`                      |
 | [`packs`](#packs)                           | array                                                                      | yes, at least one entry, in a `systems` or `modules` package; refused in a `documentation` package | —                         |
 | [`docs`](#docs)                             | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                      |
 | [`site`](#site)                             | object                                                                     | no                                                                                                 | see [`site`](#site)       |
@@ -89,7 +90,7 @@ authoring.
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, currentDate, defaultCalendar, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, currentDate, defaultCalendar, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, languages, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -196,7 +197,7 @@ build writes its `name` as `params.author`. `null` when `authors` is empty.
 as an unknown key, at the key's own line, because `authors` is the one list a
 package names its people in:
 
-> ``package-build config: `author` is not a recognized option (expected one of: rootDir, contentPackage, currentDate, defaultCalendar, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog).``
+> ``package-build config: `author` is not a recognized option (expected one of: rootDir, contentPackage, currentDate, defaultCalendar, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, languages, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog).``
 
 `package.json`'s own `author` is npm's and is not read.
 
@@ -722,6 +723,68 @@ any finding it reports is a refusal, joined into one message:
 
 > ``package-build config: `icons` <findings, semicolon-joined>.``
 
+### `languages`
+
+**Type:** object (name → `{tag, note?}`) · **Optional** · default: `{}`.
+
+The languages a note may tag text with, by short name. A note writes the short
+name, as in `[Daimela, helthos.]{lang=vyl}`; the build gives the text the
+language's tag. See
+[marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
+
+```yaml
+languages:
+  vyl: { tag: art-x-vyl, note: skill-vylarilng }
+  khel: { tag: art-x-khel }
+```
+
+| Key                     | Type                       | Required |
+| ----------------------- | -------------------------- | -------- |
+| `languages.<name>.tag`  | BCP 47 language tag        | yes      |
+| `languages.<name>.note` | Address of a language note | no       |
+
+**The name** is lowercase letters, digits and single hyphens, starting with a
+letter. Lowercase is part of the rule, so no two names differ only in case. A
+real language needs no entry: `lang=la` is read as its tag.
+
+**`tag`** is the BCP 47 tag the language's text carries. A real language takes
+its own tag (`la`, `grc`). A constructed language takes `art-x-<name>`: `art`
+is the registered code for artificial languages, and the private-use part
+after `x` says which one. The tag is checked for its form and for repeated
+variants or extension singletons. Whether each subtag is registered is not
+checked.
+
+**`note`** names the language note whose `data.words` is the language's
+lexicon, as an Address in this package: `skill-vylarilng`, or the bare
+shortcode, whose type defaults to `skill`. A run marked with the language and a
+`map=` writes each word the lexicon states a native form for by that form, and
+spells every other word by the map's rows; see
+[a map reads the dictionary first](reference/format-details.md#a-map-reads-the-dictionary-first).
+Every word of such a run is a word of the lexicon, of a name the language note's
+own register lists, or a regular form of a lexicon word, and any other word is an error; see
+[a mapped run's words](authoring/links-and-markup.md#a-mapped-runs-words).
+A language with no `note` tags its text and has no lexicon. Whether the note
+resolves is checked by `package-build lint`, at the key:
+
+> ``package-build.config.yaml:5:5: error: `languages.vyl.note` is `skill-vylarilg`, which names no language note in thalorna; it names a skill note whose subType is language``
+
+The shape is checked when the configuration loads, and each fault is a
+configuration error at its key:
+
+> ``package-build config: `languages` must be a mapping of language name to `{tag}`.``
+
+> ``package-build config: `languages.Vyl` is not a name: a name is lowercase letters, digits and single hyphens, starting with a letter.``
+
+> ``package-build config: `languages.vyl` must be a mapping with `tag`.``
+
+> ``package-build config: `languages.vyl.script` is not a recognized option (expected one of: tag, note).``
+
+> ``package-build config: `languages.vyl.note` must be the Address of a language note, such as `skill-vylarilng`.``
+
+> ``package-build config: `languages.vyl.tag` must be a BCP 47 language tag, such as `art-x-vyl` for a constructed language.``
+
+> ``package-build config: `languages.vyl.tag` art_x_vyl is not a valid BCP 47 language tag; a constructed language takes `art-x-<name>`.``
+
 ### `packs`
 
 **Type:** array of pack specs · **Required, at least one entry**, in a
@@ -1842,6 +1905,13 @@ holding one is refused at the row:
 
 > ``package-build.config.yaml:<line>:<column>: error: `packageBuild.assets[<index>]` copies `<from>`, which reaches assets/images/ — the stage copies the icon and image roots itself, flat and filtered by each file's provenance, so a row copying them would ship every file unfiltered. Remove the row``
 
+A row may still copy other files into `icons/` or `images/` — a subdirectory of
+older art, say. The staged pictures are written beside them and remove nothing.
+A picture whose flat path is already a file a row staged is an error, and the
+file the row staged stays as it is:
+
+> ``<stage>/images/<basename>: error: `images/<basename>` is already in the stage, copied by a `packageBuild.assets` row; the picture `<source>` was not staged over it``
+
 | Key                             | Type                       | Required |
 | ------------------------------- | -------------------------- | -------- |
 | `packageBuild.assets[].from`    | string                     | yes      |

package/docs/content-format.md

@@ -31,6 +31,8 @@ Leading `:` captions describe the next supported block; `:@` captions also numbe
 
 A code fence with language `poetry` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [poetry](authoring/links-and-markup.md#poetry), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans).
 
+A span, a generic div or a poetry fence marks its text's language with `lang=`, the font it is set in with `font=` and a mapping with `map=`, each optional, and the runs inside a div or a fence inherit its keys. `lang=` is a name the package declares in `languages` or a BCP 47 tag, and gives the language tag alone. `font=` is a face of the installed `@heroiclands/fonts`, named by its class without `hl-`, or `mono`, `serif` or `sans`. `map=` names a mapping note: a `doc` note whose `data.map` lists the fonts it is drawn in and rows that rewrite the text before it is set, a font's own rows first. With `lang=` naming a language whose configured `note` names its language note, a word whose entry states a `native` form for the map is written by it, and the rows spell every other word. Every word of such a run is a lexicon form, a word of a name the language note's own register lists under a tongue other than `translation`, or a form a plural row, the verb pattern or an affix stating `replaces` derives from a lexicon form, and any other word is an error at the word. A character a face does not draw, after the map, is an error at the character it came from. Text with a font, a map or a declared language is plain. Every marked construct is a row of the `runs` relation, every mapping row of the `maps` relation, and every native form of the `natives` relation. See [marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
+
 Mark a name without a note as `[Name]{.name data-type="being"}`; the optional
 classification uses the declared note vocabulary. The [name-marking
 guide](authoring/links-and-markup.md#marking-names-in-prose) explains its syntax,
@@ -173,6 +175,6 @@ Places, affiliations, lore and beings may name their culture in `data.culture`,
 
 An affiliation may name the trade, temple or order tongue it keeps in its own `data.language`. An affiliation that reaches no culture is a warning, in a tree holding a culture note. A language needs no culture and no affiliation. See [type: affiliation](reference/format-details.md#type-affiliation).
 
-A language note (`type: skill`, `subType: language`) states its words in frontmatter: `data.words` states each word as a map of its form, class, field and gloss — one sense or a list of them, which a dictionary numbers — with its source, its variant forms, the pieces it is built from and a note, beside `data.classModifiers`, `data.fields` and `data.affixes`, each affix with the `kind` it makes, for a given name's ending who the name is `given` to, and the stem closes it is barred after; a zero affix states `zero: true` and no form. The notes a word is cited from are derived, not written: a note cites a word by marking it in italics in its prose, matched by form or a variant with diacritics and case set aside. The language of a word is the note it sits on, and none of it reaches the compiled Item. A daughter language names its parent in `data.family` and reads the parent's words as its own; the `language_lineage` relation joins a language to its ancestors. Classes come from the [master word classes](reference/format-details.md#word-classes). A culture or an affiliation states its own glossary entries in `data.glossary`: common words in its core vocabulary, dictionary words with a context meaning, or phrases, compounds and terms of art outside the dictionary with their own gloss. An entry naming a word of its resolved language takes the word's senses and class and links to its language entry; a `definition` supplies the entry's meaning instead. Common marks belong to the glossary's owner. A language note with nonempty `data.words` receives its full Dictionary section automatically: one alphabetical list with field tags and one key. A culture or affiliation with nonempty `data.glossary` receives only its explicitly declared entries in its Glossary section; ranks and offices stand in the affiliation's own sections. A note without the relevant frontmatter receives no such section. All surfaces show these sections after the authored text, or under an existing `{#dictionary}`, `{#lexicon}` or `{#glossary}` heading after its introduction. There are no setting-wide dictionary or glossary pages. Every entry resolves to a language — its own `language`, else the affiliation's, its parents' or its culture's, else the culture's — or is an error at the entry. The `words`, `affixes`, `fields`, `glossary` and `language_lineage` relations hold them for `sql` fences, the `dictionary` relation lists each word under every language that has it, inherited words included, and the `terms` relation each glossary entry, rank and office with its culture associations; a fence sets custom views with `layout=dictionary` or `layout=glossary`. A language note names the tag a dictionary prints for it in `data.abbreviation`. Every fact a check reads about a language's names, sounds and history is frontmatter too: `data.tongues` and `data.register` (every name the setting gives in the language's reach, the notes carrying each derived from the index), `data.retired`, `data.scope`, `data.sounds` (letters with their place, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule, syllable finals, syllable rules and vowel harmony with each vowel's front partner, the joining of parts, written marks, a root's skeleton vowel and frames, the spellings read past, and named mutations such as wearing and voicing), `data.soundChanges` (named sets of ordered steps), `data.elements` (each standing `opening`, `closing`, `either` or `link`, for one kind of name, with the word it is the stem of and its joining form), `data.roots`, `data.cognates` (with a reconstructed `proto` form), `data.callingNames`, `data.older` (the forms older than the rules), `data.negation` (the negative particle and the mutation it brings) and `data.naming` (how long each class of name runs, the edges names keep that words do not, the element kinds each kind of name draws on, what a place name takes from what it is held from, and the near name), each a relation — `sounds` as `letters`, `edges`, `clusters`, `cluster_groups`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past` and `mutations`, `soundChanges` as `sound_changes`, `callingNames` as `calling_names` — that a fence sets back on the page. A word's citations also come from a note whose name, alias or rank or office title spells it whole. See [a language's words](reference/format-details.md#a-languages-words), [a language's register, sounds and history](reference/format-details.md#a-languages-register-sounds-and-history), [glossary terms](reference/format-details.md#glossary-terms) and [dictionaries and glossaries](reference/format-details.md#dictionaries-and-glossaries).
+A language note (`type: skill`, `subType: language`) states its words in frontmatter: `data.words` states each word as a map of its form, class, field and gloss — one sense or a list of them, which a dictionary numbers — with its source, its variant forms, the pieces it is built from and a note, beside `data.classModifiers`, `data.fields` and `data.affixes`, each affix with the `kind` it makes, for a given name's ending who the name is `given` to, and the stem closes it is barred after; a zero affix states `zero: true` and no form. The notes a word is cited from are derived, not written: a note cites a word by marking it in italics in its prose, matched by form or a variant with diacritics and case set aside. The language of a word is the note it sits on, and none of it reaches the compiled Item. A daughter language names its parent in `data.family` and reads the parent's words as its own; the `language_lineage` relation joins a language to its ancestors. Classes come from the [master word classes](reference/format-details.md#word-classes). A culture or an affiliation states its own glossary entries in `data.glossary`: common words in its core vocabulary, dictionary words with a context meaning, or phrases, compounds and terms of art outside the dictionary with their own gloss. An entry naming a word of its resolved language takes the word's senses and class and links to its language entry; a `definition` supplies the entry's meaning instead. Common marks belong to the glossary's owner. A language note with nonempty `data.words` receives its full Dictionary section automatically: one alphabetical list with field tags and one key. A culture or affiliation with nonempty `data.glossary` receives only its explicitly declared entries in its Glossary section; ranks and offices stand in the affiliation's own sections. A note without the relevant frontmatter receives no such section. All surfaces show these sections after the authored text, or under an existing `{#dictionary}`, `{#lexicon}` or `{#glossary}` heading after its introduction. There are no setting-wide dictionary or glossary pages. Every entry resolves to a language — its own `language`, else the affiliation's, its parents' or its culture's, else the culture's — or is an error at the entry. The `words`, `affixes`, `fields`, `glossary` and `language_lineage` relations hold them for `sql` fences, the `dictionary` relation lists each word under every language that has it, inherited words included, and the `terms` relation each glossary entry, rank and office with its culture associations; a fence sets custom views with `layout=dictionary` or `layout=glossary`. A language note names the tag a dictionary prints for it in `data.abbreviation`. Every fact a check reads about a language's names, sounds and history is frontmatter too: `data.tongues` and `data.register` (every name the setting gives in the language's reach, the notes carrying each derived from the index, and a name tagged `other:<tongue>` or `exonym:<tongue>` one that the tongue's own language note registers under that tongue), `data.retired`, `data.scope`, `data.sounds` (letters with their place, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule, syllable finals, syllable rules and vowel harmony with each vowel's front partner, the joining of parts, written marks, a root's skeleton vowel and frames, the spellings read past, and named mutations such as wearing and voicing), `data.soundChanges` (named sets of ordered steps), `data.elements` (each standing `opening`, `closing`, `either` or `link`, for one kind of name, with the word it is the stem of and its joining form), `data.roots`, `data.cognates` (with a reconstructed `proto` form), `data.callingNames`, `data.older` (the forms older than the rules), `data.negation` (the negative particle and the mutation it brings) and `data.naming` (how long each class of name runs, the edges names keep that words do not, the element kinds each kind of name draws on, what a place name takes from what it is held from, and the near name), each a relation — `sounds` as `letters`, `edges`, `clusters`, `cluster_groups`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past` and `mutations`, `soundChanges` as `sound_changes`, `callingNames` as `calling_names` — that a fence sets back on the page. A word's citations also come from a note whose name, alias or rank or office title spells it whole. See [a language's words](reference/format-details.md#a-languages-words), [a language's register, sounds and history](reference/format-details.md#a-languages-register-sounds-and-history), [glossary terms](reference/format-details.md#glossary-terms) and [dictionaries and glossaries](reference/format-details.md#dictionaries-and-glossaries).
 
 Blockquote alerts use `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!]`, with optional attributes after the marker. They replace the former info and warn div fences; secret blocks remain supported. See [alerts](authoring/links-and-markup.md#alerts).

package/docs/guides/book.md

@@ -503,6 +503,17 @@ successfully. The [content format](../content-format.md) covers icon names
 written in notes; the [configuration reference](../configuration.md) covers
 the font registry.
 
+### Fonts for marked text
+
+Text marked with `font=` and one of the faces of `@heroiclands/fonts` is set in
+that face once the package installs the fonts package in `devDependencies`.
+The build then adds the fonts package's `fonts/` directory, which holds the
+TrueType files, to the compiler's font search path after the shipped faces and
+`fonts.path`. `font=serif`, `sans` and `mono` set the book's own serif, sans and
+mono. A package without the fonts, or whose notes set no text in a face,
+searches the same directories as before. See
+[marking language, font and mapping](../authoring/links-and-markup.md#marking-language-font-and-mapping).
+
 ## Build and inspect
 
 ```bash

package/docs/guides/module-project.md

@@ -689,6 +689,22 @@ package-build: Cannot stage assets — these paths do not exist:
    lang
 ```
 
+### Fonts for marked text
+
+A module shows text marked with `font=` and one of the faces of
+`@heroiclands/fonts` in that face once the package installs the fonts package
+in `devDependencies`. Nothing is configured: the build reads which faces the
+notes use from their `font=` keys.
+
+`package-build assets` then stages the font stylesheet, the WOFF2 files and the
+licence under `fonts/heroiclands/` in the package; the staged stylesheet lists
+only the WOFF2 sources, since the TrueType files are not staged. The generated manifest
+names the stylesheet in `styles`, after the shared base sheet and before the
+package's own. A package that has not installed the fonts, or whose notes set
+no text in a face, stages nothing and its manifest names nothing. The stage
+refuses a fonts package that lacks its stylesheet, its licence or a file its
+manifest lists, with a finding at the fonts package's `fonts.json`.
+
 ## Step 9 — generate the manifest
 
 ```console

package/docs/guides/site.md

@@ -182,6 +182,25 @@ The build writes these keys; [what the theme draws](../reference/theme-pages.md)
 describes the panel each one feeds — the infobox, the hero band, the related
 card, and search — and the generated sections the theme draws as any other.
 
+## Show marked text in its font
+
+A site shows text marked with `font=` and one of the faces of
+`@heroiclands/fonts` in that face once the package installs the fonts package
+in `devDependencies`, as the
+[authoring guide](../authoring/links-and-markup.md#marking-language-font-and-mapping)
+describes. Nothing else is configured: the build reads which faces the notes use
+from their `font=` keys.
+
+`package-build site` copies the font stylesheet, the WOFF2 files and the
+licence to a path that names the fonts package's version,
+`fonts/heroiclands/<version>/` beside the pages, and the theme links the
+stylesheet from every page. The copied stylesheet lists only the WOFF2
+sources, since the TrueType files are not copied. `package-build site-root` gives that path a
+one-year, immutable cache lifetime in `_headers`. A package that has not
+installed the fonts, or whose notes set no text in a face, ships no font files
+and its pages carry no link. `font=serif`, `sans` and `mono` need no fonts
+package.
+
 ## Build and serve
 
 ```bash