@heroiclands/package-build 25.1.3 → 25.2.1

package/docs/authoring/links-and-markup.md

@@ -15,7 +15,7 @@ An Address names content independently of its filename or folder. Its full form
 ![[icon-harbor|Harbor emblem]]{float=top-left size=medium}
 ```
 
-The part after `|` is the displayed link text or an embed's alternative text. An empty label uses the target's current name in a regular link and marks an embed decorative. A missing pipe is an error. Search may use `name.full` and aliases; authored links use Addresses. The [Address reference](../reference/format-details.md#addresses) explains short forms, package qualification, and ambiguity diagnostics.
+The part after `|` is the displayed link text or an embed's alternative text. An empty label uses the target's current name in a regular link and marks an embed decorative. A missing pipe is an error. Search may use `name.full` and the forms a note's `name` lists; authored links use Addresses. The [Address reference](../reference/format-details.md#addresses) explains short forms, package qualification, and ambiguity diagnostics.
 
 A link to a note tagged `draft` retains its target and carries a visible draft cue. In a book, the cue reads `(draft)` after the link.
 
@@ -61,19 +61,19 @@ destination; see [inline spoilers](#inline-spoilers).
 
 ## Marking names in prose
 
-Use `[Name]{.name}` for a name that has no indexed note. Link a name that has
-one, including a private subject; an empty link label uses the indexed full
-name. Introduce another subject with its full canonical name at its first prose
-use. Keep the note's own subject in plain text, and use plain text for later
-mentions and aliases. Bold is emphasis.
-Plain text, including capitalized words, is not searched for names.
+Mark a name with a link or a `.name` span. Link a name that has a note,
+including a private subject, and add `.name` to the wikilink so it counts as
+the name: `[[place-arden|Arden Vale]]{.name}`. An empty link label uses the
+indexed full name. Use `[Name]{.name}` for a name that has no indexed note.
+Keep the note's own subject in plain text. Plain text, including capitalized
+words, is not searched for names.
 
 Inside a language run, a `.name` child contributes `{` + its text + `}` to the
 chosen encoding. Write `[Name]{.name}` in Markdown; the build supplies the
 standard name boundaries.
 
 ```markdown
-[[place-arden|Arden Vale]] stands beside the river. Arden Vale has two gates.
+[[place-arden|Arden Vale]]{.name} stands beside the river. Arden Vale has two gates.
 [Hidden Hand]{.name} keeps watch over the crossing.
 ```
 
@@ -93,21 +93,73 @@ takes only the bare type. An invalid supplied value is an error at the
 attribute. Site and Foundry spans retain the classes and attribute values;
 the attribute adds no book presentation.
 
-`package-build lint` warns when an indexed name or alias uses `.name`
-instead of a link, when the same name is marked or linked again, or when a
-`.name` span or Markdown link uses a short form before its full name. A
-`.name` span with a `data-type` is compared only with notes of that type (and
-subtype, when it names one), so a lineage that shares its name with a place
-note is marked `[Theinuvael]{.name data-type="affiliation/lineage"}` and
-draws no warning to link the place. Only
-marked names and authored link labels count toward these rules. A wikilink
-introduces its note under whatever label reads naturally, so
-`[[place-arden|Arden]]` needs no earlier `Arden Vale`, and an article
-mid-sentence stays lowercase. A `.name` span introduces the full name before
-an alias such as `Arden`. Later mentions are plain text. Full names and their
-declared aliases count as the same name, including in links to different
-headings. Different labels do not become the same name just because they link
-to the same page.
+A `ref` ties each spelling of a person, place or thing to the one note that
+describes it, without linking it. The address implies the type, so `data-type`
+is only for a name with no note:
+
+```markdown
+[Tom Rodriguez]{.name ref=being-tomr} met [Tom]{.name ref=being-tomr} again.
+[Tom]{.name ref=sohl-note-being-tomr}
+```
+
+The value is a note address: this package's (`being-tomr`) or a declared
+dependency's, written with its package prefix (`sohl-note-being-tomr`). A
+`ref` is not a link, so the span stays plain text and the page links the note
+once, with a wikilink, wherever the author chooses. A `ref` span names the note
+however it is spelled, so it draws no warning to link the name, and it shares
+the note's key for the [first-use bold](#the-first-use-is-bold).
+A `ref` that resolves to no note is an error at its value. `data-type` beside
+`ref` is an error at `data-type`, and `ref` on a span without `.name` is an
+error at `ref`. A wikilink never takes `ref`, because its address is its ref.
+Use `#id` for the HTML anchor only; it is never a ref.
+
+A subject with no note takes a page-local key instead, written with a leading
+`#` and quoted when it stands alone as a value:
+
+```markdown
+[Jane Doe]{.name ref="#jane"} arrives. [Miss Gorgeous]{.name ref="#jane"} is Jane.
+```
+
+The key ties _Jane Doe_ and _Miss Gorgeous_ to one person within the page. It
+resolves to no note and is never a finding for that reason. It is the
+attribute's value, never the span's `{#id}` anchor.
+
+### The first use is bold
+
+The first use of each name in a page is bold when the page renders, on the
+website, in the Foundry journal and in the book, and every later use reads as
+plain text. Bold an author writes is the author's choice.
+
+Each use of a name is counted under a key:
+
+- a name wikilink, `[[place-harbor|the harbor]]{.name}`, under its address;
+- a `.name` span with a `ref`, under the `ref`, whether an address or a
+  page-local `#key`;
+- any other `.name` span under its label, ignoring case, and its `lang`, which
+  is `en` when the span states none.
+
+Every spelling of one address is one key, so `[[place-arden|the vale]]{.name}`
+and `[Vale]{.name ref=place-arden}` are one name. A `ref` is how a full name,
+a short name and a nickname become one name:
+
+```markdown
+[Jane Doe]{.name ref="#jane"} keeps the ferry to [[place-harbor|the harbor]]{.name}.
+[Jane]{.name ref="#jane"} rows it alone, and the river folk call her
+[Miss Gorgeous]{.name ref="#jane"}. [Old Tam]{.name} mends the nets at
+[[place-harbor|the harbor]]{.name}, and [old tam]{.name} sells them.
+```
+
+Here _Jane Doe_, the first _the harbor_ and _Old Tam_ are bold. _Jane_ and
+_Miss Gorgeous_ share _Jane Doe_'s key, the second _the harbor_ shares the
+first's address, and _old tam_ is _Old Tam_ in another case.
+
+Only body prose counts, in the order it is written: paragraphs, list items,
+quotations and footnotes. A name in a heading, a table, a caption, raw HTML,
+code or verse, in the sections the build generates from frontmatter, or inside
+a run that states `lang`, `font` or `enc` neither takes the bold nor counts, so
+the first use in the prose after a heading or table that names someone is
+still bold. A wikilink without `.name` is a link, not a name: it takes no bold
+and does not count.
 
 A name span can sit inside emphasis:
 
@@ -115,12 +167,22 @@ A name span can sit inside emphasis:
 **This is a phrase with [Joe Blow]{.name} in it**
 ```
 
-The marked name is `Joe Blow`. Sites and books display `.name` text in bold, including
-inside an emphasized phrase. Bold itself is emphasis, never a name: a bold
+The marked name is `Joe Blow`. A name inside authored bold counts as that
+name's first use and takes no second bold. Bold itself is never a name: a bold
 label such as `**Strength**:` draws no warning, whatever names the index holds.
 
-These are warnings at each occurrence's `file:line:column`; they do not make
-a valid package fail. The check reads authored prose outside headings,
+### What lint reports
+
+`package-build lint` warns when an indexed name or listed form uses a `.name`
+span with no `ref`, which a link or a `ref` ties to its note. A `.name` span
+with a `data-type` is compared only with notes of that type (and subtype, when
+it names one), so a lineage that shares its name with a place note is marked
+`[Theinuvael]{.name data-type="affiliation/lineage"}` and draws no warning to
+link the place. Names match whatever their case, so `[arden]{.name}` names the
+same note as `[Arden]{.name}`.
+
+This is a warning at each occurrence's `file:line:column`; it does not make a
+valid package fail. The check reads authored prose outside headings,
 tables, infoboxes, code, frontmatter, comments and embeds. See the
 [complete name-marking rules](../reference/format-details.md#marking-names-in-prose).
 
@@ -130,7 +192,7 @@ its visible text, optional type/subtype and source location. Plain prose, bold,
 unmarked link labels and generated content add no rows.
 
 Lint also gives one grouped package advisory for names without a matching
-indexed full name or alias, and for conflicting supplied classifications. It
+indexed full name or listed form, and for conflicting supplied classifications. It
 lists every use and starts at the earliest reported span. Untyped uses do not
 conflict, and `place` agrees with `place/settlement`; different supplied types
 or different supplied subtypes conflict. These advisories do not fail lint.
@@ -267,7 +329,7 @@ hover the span or focus it with the keyboard to reveal its text, links and
 images. A visible focus outline and a spoiler cue identify the interaction.
 This does not change native Foundry secret-section controls. The book ignores
 `.secret` on inline spans and prints their text normally, preserving emphasis,
-links, anchors and `.name` bold styling. Secret sections and `:::secret` fences
+links, anchors and a name's first-use bold. Secret sections and `:::secret` fences
 retain their visible labelled boxes.
 
 Published web HTML contains the spoiler's text. Revealing the spoiler or reading
@@ -1967,8 +2029,7 @@ printing a sense several bodies give once, with all of them:
 
 The layout orders entries by letter, then by `name_sort`. **The language tag
 prints where the entry's language is not the page's own**: a language note's
-own language, a culture's `data.language`, or the language an affiliation's
-glossary resolves to. It is the language note's `data.abbreviation`, or its
+own language, or the note of any other note's [language](../reference/format-details.md#a-notes-language). It is the language note's `data.abbreviation`, or its
 full name where unstated. Etymology never repeats the entry's own language:
 a borrowed word prints `[fr. Élav. _sólmerë_]`, a built word its pieces each
 with its gloss, `[_am-_ "love" + _-ère_ "one who"]`, an inherited word its

package/docs/commands.md

@@ -978,31 +978,52 @@ package-build changelog check [--release] [paths..]
 **DESCRIPTION**
 
 A changeset answers one question — who notices, and what do they see — and
-nothing enforced that, so a pull-request description pasted into one ships
-verbatim as a release note: commit hashes, issue references, code fences,
-"Verified" paragraphs, byte counts and test tallies, a paragraph disguised as
-a bullet, a nested checklist, a `#` heading that outranks the version heading
-above it once wrapped into a list item, or simply too many bullets or too
-many lines for one entry. Each finding names the rule it tripped and says
-what to write instead.
+holds one shape: one or more blocks, each a `**Label**` line on its own,
+then bullets and nothing else. `check` refuses a lead paragraph, a bullet
+under no label (`unlabelled`), prose between or after bullets (`stray-prose`),
+text sharing the label's line (`label-line`), a label with no bullets
+(`empty-block`), a nested list, a `#` heading, and a label that is neither in
+the changelog `labels` nor `Miscellaneous` (`unknown-label`, an error naming
+the declared labels). With no `labels` declared, only
+`Miscellaneous` is accepted, and the finding names the option to declare.
+
+**Labels.** A repository declares its labels, in display order, in the options
+of the changelog entry in `.changeset/config.json`, beside the generator they
+configure:
+
+```json
+"changelog": [
+    "@heroiclands/package-build/changelog",
+    { "labels": ["Verse", "Rendering"] }
+]
+```
+
+`Miscellaneous` is implicit: every repository has it for the changes that fit
+no declared label, it is never declared, and `changelog group` always writes it
+last. A `labels` value that is not an array of distinct non-empty strings, or
+that names `Miscellaneous`, stops `changelog check` and `changelog group`
+with an error naming `.changeset/config.json`.
+
+Under the shape, a changeset that reads like a pull-request description is
+also refused: commit hashes, issue references, code fences, "Verified"
+paragraphs, byte counts and test tallies, a bullet over forty words, or too
+many bullets or lines for one entry. Each finding names the rule it tripped
+and says what to write instead.
 
 Default reads every pending changeset (`.changeset/*.md`; `config.json` and
 `README.md` excluded) and checks each one's body, frontmatter fence dropped.
 `--release` reads the first `## <version>` section of `CHANGELOG.md` instead
-— the section a **Version Packages** branch is about to publish — with its
-generated `## <version>` and `### <Bump> Changes` scaffold lines exempted
-from the heading rule, since neither is authored.
+— the section a **Version Packages** branch is about to publish — and holds
+it to the same shape. Its generated `## <version>` line is exempt, and a
+`### <Bump> Changes` heading that remains is an error (`changes-heading`):
+`changelog group` removes them.
 
 A token that reads as code — `camelCase()`, a `path/with/slashes.ext`,
 `SCREAMING_SNAKE` — outside any code span is a warning, not a failure: a
 user-facing note sometimes needs one (`Compendium.hm3.items.Item.<id>`), but
 rarely. Accented letters keep proper names such as HârnMaster whole, so a
-fragment of one does not trigger a code-token warning. A block's bold label
-absent from a declared `changelog.labels` is
-also a warning — the drift `**Character data**` beside `**Characters**`
-produces — and checks nothing when the repository declares no
-`changelog.labels`. Every other finding is an error. Reads the files given,
-or resolves its own defaults; writes nothing.
+fragment of one does not trigger a code-token warning. Every other finding is
+an error. Reads the files given, or resolves its own defaults; writes nothing.
 
 **OPTIONS**
 
@@ -1024,8 +1045,8 @@ package-build: 1 file(s) checked · 0 error(s) · 0 warning(s)
 ```
 
 ```
-$ package-build changelog check --release
-CHANGELOG.md:5:3: error: changelog-check/commit-hash a commit hash is a commit-log artefact; the changelog generator should not write one — set `changelog` to `@changesets/cli/changelog`
+$ package-build changelog check
+.changeset/stanza-breaks.md:5:3: error: changelog-check/unknown-label "Poems" is not a declared label — declared: Verse, Rendering; Miscellaneous is always available
 package-build: 1 file(s) checked · 1 error(s) · 0 warning(s)
 ```
 
@@ -1037,8 +1058,8 @@ package-build: 1 file(s) checked · 1 error(s) · 0 warning(s)
 
 **NAME**
 
-Fold a release section's changeset blocks together by their bold label
-(`group` is a sibling of `check`, not one of its actions).
+Give the newest release its final shape (`group` is a sibling of `check`,
+not one of its actions).
 
 **SYNOPSIS**
 
@@ -1049,27 +1070,46 @@ package-build changelog group [paths..]
 **DESCRIPTION**
 
 `@heroiclands/package-build/changelog` writes each changeset's summary into
-`CHANGELOG.md` as its own block, verbatim, under `### <Bump> Changes` — one
-per changeset, in whatever order Changesets read the files. Three pull
-requests each touching compendium content each write their own
-`**Compendiums**` block, and nothing merges them: the release reads as three
-scattered entries instead of one.
-
-`group` rewrites the first `## <version>` section of `CHANGELOG.md` in
-place. Within each `### <Bump> Changes` body, every block sharing one bold
-label is merged into a single block for that label. Prose and bullets are
-retained, with exact duplicate items kept once. Opening paragraphs from
-merged labels combine in source order before their items. Wrapped
-paragraphs, nested item content and literal code stay intact. The merged
-blocks are reordered: the unlabelled lead paragraph a
-changeset writes with no category first, then every label
-[`changelog.labels`](configuration.md#changelog) declares, in the order
-given, then any label absent from that list last, in the order it first
-appeared — each reported as a warning naming it. With no `changelog.labels`
-declared, every group instead keeps the order its label first appeared in,
-lead paragraph first, and nothing is reported as unknown. Every earlier
-release section is untouched, byte for byte. Running `group` on its own
-output is a no-op.
+`CHANGELOG.md` as its own block, verbatim, under `### Major Changes`,
+`### Minor Changes` or `### Patch Changes` — one block per changeset, in
+whatever order Changesets read the files. `group` rewrites the first
+`## <version>` section of `CHANGELOG.md` in place:
+
+- Every `### … Changes` heading is removed.
+- Blocks that share a label merge into one, bullets in file order, an exact
+  duplicate bullet kept once.
+- Blocks are ordered as the `labels` in `.changeset/config.json`
+  declare them. A label the list does not declare follows the declared ones, in the order it first appeared, each reported as a
+  warning naming it.
+- `Miscellaneous` is always last, declared or not.
+
+With no `labels` declared, blocks keep the order their label first
+appeared in, `Miscellaneous` last. Every earlier release section is untouched,
+byte for byte. Running `group` on its own output is a no-op.
+
+For a release of three changesets, `### Major Changes` holding
+`**Rendering**` and `**Miscellaneous**`, `### Minor Changes` holding `**Verse**`
+and `**Rendering**`, and `### Patch Changes` holding `**Miscellaneous**` and
+`**Verse**`, with `labels` of `Verse` then `Rendering`:
+
+```markdown
+## 2.0.0
+
+**Verse**
+
+- A verse fence keeps its line breaks.
+- A stanza break renders as a blank line.
+
+**Rendering**
+
+- Every page carries its section in the contents list.
+- The search page lists the newest notes first.
+
+**Miscellaneous**
+
+- The tool prints a notice when a page has no title.
+- An empty search no longer fails.
+```
 
 **OPTIONS**
 
@@ -1091,14 +1131,14 @@ package-build: 1 file(s) grouped · 0 warning(s)
 
 ```
 $ package-build changelog group
-CHANGELOG.md:12: warning: changelog-group/unknown-label "Scenery" is not declared in `changelog.labels` — filed last, in order of first appearance
+CHANGELOG.md:12: warning: changelog-group/unknown-label "Scenery" is not declared in the changelog `labels` — filed after the declared labels, in order of first appearance
 package-build: 1 file(s) grouped · 1 warning(s)
 ```
 
 **SEE ALSO**
 
 [`changelog check`](#package-build-changelog-check),
-[`changelog.labels`](configuration.md#changelog).
+[`.changeset/config.json` labels](#package-build-changelog-check).
 
 ### `package-build bundle check`
 
@@ -2223,20 +2263,23 @@ explicit empty inventory declares no written characters. External tags without
 a language-note association retain their ordinary behavior. Standalone
 `package-build markdown` does not load these inventories.
 
-Name marking is advisory: lint checks explicit `.name` spans and authored link
-labels against the [name-marking
-conventions](authoring/links-and-markup.md#marking-names-in-prose). Plain prose
-is not searched for names. It builds one matcher from the current local and
-dependency names, then
-reports each affected occurrence at its exact source location. These warnings
+Name marking is advisory: lint checks explicit `.name` spans and name
+wikilinks against the [name-marking
+conventions](authoring/links-and-markup.md#marking-names-in-prose). It warns
+when a `.name` span without `ref` names an indexed note. Plain prose is not searched
+for names. It builds one matcher from the current local and dependency names,
+then reports each affected occurrence at its exact source location. These warnings
 also appear when `lint` is selected in `content run`; they do not fail the run.
 
 Lint also emits one grouped package advisory for marked names without an
-indexed full-name or alias match, and for conflicting supplied classifications.
+indexed full-name or listed-form match, ignoring case, and for conflicting supplied classifications.
 It lists every source use and is located at the earliest reported span.
 Untyped uses and compatible type/subtype refinements do not conflict.
 An invalid supplied `.name` `data-type` is a located preparation error and
 prevents selected writers. See the same name-marking guide for typed examples.
+A `.name` `ref` that resolves to no note is a located lint error at its value;
+a `ref` on a span without `.name`, a `ref` beside `data-type` and a malformed
+page-local key are located preparation errors.
 
 Content lint computes source positions when it emits findings and shares each
 note's YAML position document across consecutive lookups.
@@ -3484,17 +3527,18 @@ culture missing either, with an error at the culture note:
 - **Its look**, from `data.appearanceProfile`: the words and ranges every
   appearance field is drawn from. See
   [appearance profiles](reference/format-details.md#appearance-profiles).
-- **Its names**, from the language skill note its `data.language` names, whose
+- **Its names**, from the language note `languages:` names for the culture's
+  [language](reference/format-details.md#a-notes-language), whose
   `data.names` holds the pattern and the lists. A language with no
   `data.names` is an error at the language note. See
   [name lists](reference/format-details.md#name-lists).
 
-The content-index JSONL resolves a culture's `data.language` and
-`data.appearanceProfile` before this command reads them. A child culture may
-inherit each omitted field from its `data.parents`, while a stated value keeps
-precedence. The command consumes the resolved values and keeps the selected
-child culture on the generated note. A parent cycle or conflicting inherited
-sources are errors; complete fields on the selected culture do not excuse a
+The content index resolves a culture's language and its
+`data.appearanceProfile` before this command reads them. A child culture
+takes an omitted `data.lang` or profile from its `data.parents`, while a stated
+value keeps precedence. The command consumes the resolved values and keeps the
+selected child culture on the generated note. A parent cycle or conflicting
+inherited profiles are errors; complete fields on the selected culture do not excuse a
 cycle. See [culture parents](reference/format-details.md#culture-parents-and-inherited-fields).
 
 A profile or name lists with problems are refused with a finding at each.
@@ -3605,11 +3649,11 @@ $ package-build npc new --specfile bad.yaml
 bad.yaml:2:9: error: name.full "Aguri ez Lut" does not fit the names of demo-note-skill-khelathilng: "Lut", the {place} part, is not in the place list
 ```
 
-A spec inline, for a culture that names no language:
+A spec inline, for a culture whose language has no language note:
 
 ```
 $ package-build npc new --spec '{"data":{"culture":"plainfolk","gender":"female"}}'
-assets/content/Cultures/Plainfolk.md:6:1: error: demo-note-lore-plainfolk states no `data.language`, so `npc new` has no name lists to draw from; name the language skill note its people speak
+assets/content/Cultures/Plainfolk.md:6:1: error: demo-note-lore-plainfolk is in en, 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`
 ```
 
 **SEE ALSO**

package/docs/configuration.md

@@ -54,7 +54,7 @@ around its own evaluation.
 
 ### Quick reference
 
-26 top-level keys. `rootDir` is not one of them — a data configuration never
+25 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
@@ -86,11 +86,10 @@ authoring.
 | [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                    |
 | [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                      |
 | [`publish`](#publish)                       | object                                                                     | no                                                                                                 | `{address: {prefix: ""}}` |
-| [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`          |
 
 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, languages, 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). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -201,7 +200,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, languages, 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).``
 
 `package.json`'s own `author` is npm's and is not read.
 
@@ -749,7 +748,12 @@ languages:
 
 **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.
+real language needs no entry: `lang=la` is read as its tag. The name is the
+language's code everywhere a note names a language: `lang=` on a run, a note's
+[`data.lang`](reference/format-details.md#a-notes-language), and the key a
+note's `name` lists the language's forms under. `en` needs no entry for any of
+these. A name may not be `full`, `sort`, `given` or `clan`, the `name` keys
+that hold a single string.
 
 **`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`
@@ -1831,45 +1835,6 @@ Any other key under `publish.address` is refused:
 
 > ``package-build config: `publish.address.<key>` is not a recognized option (expected one of: prefix).``
 
-### `changelog`
-
-**Type:** object · **Optional**, default `{labels: null}`.
-
-`changelog check` and `changelog group` both read a release block's bold
-label — `**Compendiums**` — against `changelog.labels`: the vocabulary and
-display order a repository declares for the categories its changesets group
-under. Declaring none is ordinary — a repository that writes plain,
-unlabelled changesets needs nothing here.
-
-| Key                | Type     | Required | Default |
-| ------------------ | -------- | -------- | ------- |
-| `changelog.labels` | string[] | no       | `null`  |
-
-> ``package-build config: `changelog` must be a mapping.``
-
-> ``package-build config: `changelog.<key>` is not a recognized option (expected one of: labels).``
-
-> ``package-build config: `changelog.labels` must be an array.``
-
-> ``package-build config: `changelog.labels[<n>]` must be a non-empty string.``
-
-A repeated label is refused rather than silently deduplicated — it could
-never be told apart from the drift the list exists to catch (`Compendiums`
-written twice swallows a genuine `Character data` beside `Characters`):
-
-> ``package-build config: `changelog.labels` declares `Compendiums` more than once.``
-
-With `changelog.labels` declared, `changelog group` orders a release
-section's blocks by that list — the unlabelled lead paragraph first, then
-every declared label in the order given, then any undeclared label last, in
-the order it first appears, each reported as a warning naming it. With no
-`changelog.labels` declared, `group` orders every block by first
-appearance, lead paragraph first, and warns about nothing. `changelog check`
-warns on a block whose label is not in a declared `changelog.labels`; with
-none declared, it checks nothing. See
-[`package-build changelog check`](commands.md#package-build-changelog-check)
-and [`package-build changelog group`](commands.md#package-build-changelog-group).
-
 ---
 
 ## The `packageBuild` section
@@ -2044,7 +2009,7 @@ named first in the generated manifest's `styles`.
 The sheet carries what every package's compiled content needs to read in
 Foundry as it does in the preview and on the site: definition lists (an
 infobox and the markdown `Term` / `: definition` syntax both emit one),
-verse, alerts, inline spoilers, marked names in bold, unresolved links and
+verse, alerts, inline spoilers, unresolved links and
 captioned blocks. It is scoped to the journal, enriched-field and editor
 containers so it cannot reach Foundry's own interface, where `.name` and `dl`
 style Foundry's and the system's own elements.

package/docs/content-format.md

@@ -25,7 +25,7 @@ Start with [your first note](authoring/first-note.md). It explains the smallest
 
 ## The shared note
 
-A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
+A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. Each page name is its heading's visible text: spans, links and emphasis contribute their text without their markup. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
 
 Leading `:` captions describe the next supported block; `:@` captions also number it. The optional type accepts `figure`, `table`, `verse`, `code`, `prose`, and `example`. Captions support identifiers, classes and named attributes; unsupported following blocks are errors. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references).
 
@@ -172,19 +172,21 @@ A region may list its settlements in a table under `## Settlements` — name, ma
 
 A being states its gender, frame and appearance in words from one closed vocabulary: `data.gender`, `data.frame`, and `data.appearance.eye_color`, `hair_color`, `skin_color` and `complexion` each take only the words listed for them, and any other value is an error at the value. `complexion` is a list, required once a being states an appearance. `data.appearance.extra_features` lists the being's visible physical marks, each a short plain description of one, and an entry stating a colour, a skin condition or anything that is not a mark is an error. See [a being's look](reference/format-details.md#a-beings-look).
 
-A culture note may state what its people look like in `data.appearanceProfile`: weighted words for frame, eyes, hair, skin and complexion, and height ranges by gender, all from the same vocabulary. A culture names its tongue in `data.language`, and that language skill note may state `data.names`: the patterns its speakers' names are built by and the lists each part is drawn from. `package-build npc new` writes a complete npc note from a spec of a culture and a gender, drawing the name from those lists and everything else the spec leaves out from the profile. See [appearance profiles](reference/format-details.md#appearance-profiles), [name lists](reference/format-details.md#name-lists) and [the command](commands.md#package-build-npc-new).
+A culture note may state what its people look like in `data.appearanceProfile`: weighted words for frame, eyes, hair, skin and complexion, and height ranges by gender, all from the same vocabulary. A culture's tongue is its language, and the note `languages:` names for that language may state `data.names`: the patterns its speakers' names are built by and the lists each part is drawn from. `package-build npc new` writes a complete npc note from a spec of a culture and a gender, drawing the name from those lists and everything else the spec leaves out from the profile. See [appearance profiles](reference/format-details.md#appearance-profiles), [name lists](reference/format-details.md#name-lists) and [the command](commands.md#package-build-npc-new).
 
 A culture may name its larger cultures in `data.parents`. Each entry names a
-culture lore note. Omitted `data.language` and `data.appearanceProfile` fields
-inherit independently through those parents; the content-index JSONL contains
+culture lore note. An omitted `data.appearanceProfile` inherits through those
+parents, and so does the culture's language; the content-index JSONL contains
 the resolved values, which `npc new` reads directly. A stated field wins over
 its inherited value. See [culture parents](reference/format-details.md#culture-parents-and-inherited-fields)
 for a complete example, parent ordering and findings.
 
+Every note is in one language, a code `languages:` declares or `en`. A note states it in `data.lang`; one that does not takes its culture's language, then its `data.parents`', nearest first, then `en`, and the content index publishes the result on the note's record as `lang`. A note's other names are listed in `name` under the code of their language, beside the English `full`: `name: {full: Johnathan Lewis, en: [John], vyla: [juan juis]}`. Names match whatever their case. See [a note's language](reference/format-details.md#a-notes-language) and [frontmatter](authoring/frontmatter.md).
+
 Places, affiliations, lore and beings may name their culture in `data.culture`, and a `doc` of `subType: settingguide` must. A place or affiliation that names none inherits the culture of its parents. See [culture in the index](reference/format-details.md#culture-in-the-index).
 
-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).
+An affiliation may state the trade, temple or order tongue it keeps as its own `data.lang`. 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`. A `doc` note states a setting's core concepts in `data.concepts`, a language note says it must cover them with `data.core: true`, and a word names the concepts it serves in `concept`; `package-build core` lists what each covering language has no word for (see [the core vocabulary](reference/format-details.md#the-core-vocabulary)). 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, their IPA and the tongues that write them, each a declared tag or a language note's Address, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule (`two`, `longer`, which may be `first`, and `mark`), syllable finals with their IPA, 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 `doc` note may state a spelling guide's `data.sounds.letters` and `data.sounds.marks` alone, its letter rows naming tongues by language note Addresses, and they join the `letters` and `marks` relations under the guide's Address. 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 note `languages:` names for the language of the note it is written on — 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`. A `doc` note states a setting's core concepts in `data.concepts`, a language note says it must cover them with `data.core: true`, and a word names the concepts it serves in `concept`; `package-build core` lists what each covering language has no word for (see [the core vocabulary](reference/format-details.md#the-core-vocabulary)). 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, their IPA and the tongues that write them, each a declared tag or a language note's Address, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule (`two`, `longer`, which may be `first`, and `mark`), syllable finals with their IPA, 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 `doc` note may state a spelling guide's `data.sounds.letters` and `data.sounds.marks` alone, its letter rows naming tongues by language note Addresses, and they join the `letters` and `marks` relations under the guide's Address. A word's citations also come from a note whose name, listed name form, 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).