@heroiclands/package-build 21.0.0 → 21.2.0

package/CHANGELOG.md

@@ -1,5 +1,233 @@
 # @heroiclands/package-build
 
+## 21.2.0
+
+### Minor Changes
+
+- 9ccd9e1: **Art and sound have addresses** — A package's pictures and sound clips are now
+  addressed the way its notes are. `icon`, `image` and `audio` are types a
+  reference can reach, one per tree: `assets/icons`, `assets/images` and
+  `assets/audio`. The filename is the name — `anvil.svg` is `icon-anvil` — and the
+  directories above it are the package's own business, so a tree can be tidied
+  into whatever arrangement suits the people who maintain it without a single
+  reference changing.
+  
+  - _The extension stays out of the name._ Changing a picture from SVG to WebP is
+    dropping a different file in place; nothing that names it has to be touched.
+  - _Two files cannot claim one name._ A root's names are one list however deeply
+    it nests, and the build says which two files collided.
+  - _Attribution travels with the file._ Who made it, where it came from and what
+    licence it carries are published beside it, taken from the `provenance.yaml`
+    nearest the file or from a record written for that one file alone.
+  - _A package can lend its art._ Every address says which package holds the
+    bytes, so a picture one package ships resolves for another that cites it — on
+    the website, in the book, and in Foundry.
+  - `packagebuild` is a reserved name, held for the files the toolchain itself
+    ships, so no package may claim it.
+  
+  Fonts are deliberately not addressable: nobody names a typeface the way they
+  name a picture, and a stylesheet and a typesetter each want something an address
+  cannot give them.
+- 888f64a: **An image a Foundry journal cannot serve is refused** — An image in a note's
+  body names the package that owns the file, and a journal can only draw one from
+  a package the install carries. An address naming a package the build declares no
+  relationship with — or `packagebuild`, whose shared banners travel with the
+  toolchain and belong to the website and the book — is reported with the file,
+  line and column it sits on, and the build stops rather than compiling a document
+  whose picture resolves against nothing.
+  
+  - _Both spellings, one answer._ `![alt](…)` and `![[address|label]]` are one
+    image, so an address is refused in the same words whichever way it is written.
+  - _`banner:` is where a shared banner belongs._ It reaches the page and the
+    book's section plates and no compiled document, so a note plating a section
+    with one of the toolchain's banners is doing the right thing.
+  - _An address naming no package still passes through._ A URL, a
+    protocol-relative `//host/…`, a `data:` URI and a `/`-rooted path reach a
+    journal untouched, which is how a note draws core Foundry art or art from a
+    package outside this constellation.
+- b34686f: **The shared banners can be named from anywhere** — A note borrows one of the
+  section banners the toolchain ships by naming it, and nothing has to be declared
+  or downloaded first:
+  
+  ```yaml
+  data:
+    banner: packagebuild-none-image-skillbnr
+  ```
+  
+  The pictures travel with the toolchain itself, so a package plates a section
+  without keeping its own copy and without taking on a dependency on some parent
+  system it has no other relationship with. They appear on the website and in the
+  book; Foundry installs nothing for them, which is why nothing in a compendium
+  ever names one.
+  
+  `packagebuild` is reserved, so no package can claim the name out from under
+  them.
+- 9a937e7: **A note names its art, and the art arrives** — The picture a document carries
+  is chosen by name now, the way everything else in a note is. `icon` is what a
+  directory listing shows beside the name, `tokenIcon` what a token on the canvas
+  wears, `bgImage` a map's background, and `banner` the hero image at the top of a
+  page. Write the name of the file and the build finds it.
+  
+  - _The art actually reaches the document._ Every compiled item took its type's
+    stock picture whatever its note said; it now carries the one it names, and the
+    same goes for a being's profile art, its token and its portrait.
+  - _A map is art all through._ Its background, the pictures on its tiles and the
+    sound clips placed around it are all named the same way and all resolved.
+  - _A being with no picture of its own gets one that suits it_ — a person and a
+    creature fall back to different art, chosen from what the note says it is.
+  - _A picture one package ships reaches another that names it_, on the website,
+    in the book and in Foundry, with each getting the address it serves.
+  - _`tokenIcon` unset follows `icon`._ A being naming one picture wears it on the
+    canvas too.
+  - _A name nothing answers is reported against the note_ rather than quietly
+    becoming the stock picture.
+  
+  A being's portrait is the first image inside its `{#appearance}` section now,
+  written in the prose that describes it rather than declared in a field — where
+  an author can see it, move it and caption it like any other picture.
+- 7661355: **A picture goes where it belongs in the prose** — `![[address|label]]` puts an
+  image where it is written, and every surface draws it there: a Foundry journal,
+  the website and the book alike. It is the wikilink already in use, with `!`
+  meaning _draw it here_ rather than _link to it_, so nothing new has to be
+  learned — the same short form, the same way of reaching another package's
+  artwork, the same complaint when an address names nothing.
+  
+  - _The label is what the picture says._ It is the caption in print, and the
+    words a screen reader announces when the image does not load. `![[anvil|]]`
+    says the picture is decoration and needs none.
+  - _It sits where it is told._ An embed takes the same `{…}` an image does — a
+    width, a position, or both in either order — and an unrecognised value is
+    refused with the file and line it is on rather than quietly ignored.
+  - _Only a picture can be embedded._ Naming a character or a skill where a file
+    belongs is refused, and the message says to link to it instead.
+  - _A being's portrait opens its appearance._ Every creature and every character
+    now shows its picture at the top of what it looks like, in the compendium, on
+    the page and in the book.
+- 84a6715: **Shared section banners** — package-build now ships the thirteen banner images
+  many packages draw on, and publishes them to consumers. A package can plate a
+  section without keeping its own copy, and without declaring a dependency on some
+  parent system or module to borrow one.
+  
+  They are licensed CC-BY-SA-4.0, recorded beside them.
+- 0c10ba5: **Everything a being carries now has a picture** — Gear and skills written out
+  inside a being's note, rather than copied from the catalogue, reached the sheet
+  with no artwork at all. They carry art now, by the same two rules everything
+  else does.
+  
+  - _An item can name its own._ Write an icon under `data:` and the sheet shows it.
+  - _And it takes one when it names none._ A whetstone somebody wrote out by hand
+    gets the picture every other piece of miscellaneous gear gets, instead of a
+    blank.
+- fc33f24: **The book sets in the faces the build carries, not the ones the machine has.**
+  Headings, running heads, table labels and captions are set in _Libertinus Sans_
+  — the toolchain ships it, so a book sets the same way on any machine, and the
+  sans no longer comes out in the body face because nothing could resolve it.
+  _Libertinus Mono_ is shipped beside it for a package that sets its code spans in
+  it; the default mono is unchanged.
+  
+  **A face that resolves to nothing is reported.** A compile that cannot find a
+  family still writes a book, set in whatever the fallback reached — a wrong face
+  that nobody sees. The compiler's warnings are now findings like any other, with
+  the file, the line and the column.
+
+### Patch Changes
+
+- d2d029a: **A system panel says what the module actually ships** — A page's SoHL or HM3
+  box reads _Not available_ only where that system really has no document for the
+  note, which is what a reader acts on.
+  
+  - _A note need not name a system to have one._ Where the whole of a subject
+    lives in its own fields — an affiliation, a being written without system
+    detail — the panel now carries the subject's fields instead of claiming the
+    page is outside the system's reach.
+  - _A system the module ships nothing for still says so_, on every page that
+    could have carried it.
+- 9d4ba48: **Content format** — A map names its art the way every other note does. Its
+  background is `bgImage`, an `image` address; a tile names its art with `image`
+  and an ambient sound names its clip with `audio`. A map carries no `img` — a
+  Scene has no such field.
+- acea050: **Content format** — The specification describes art as addresses rather than
+  file paths. A note names its artwork with a wikilink address, an asset lives at
+  an address that holds exactly one file with the extension outside the name, and
+  `icon`, `image`, `font` and `audio` are types a link can reach like any other.
+  
+  - The five art slots are `icon`, `portrait`, `tokenIcon`, `bgImage` and
+    `banner`, each a wikilink field with its own default type.
+  - An image in a note's body is written `![[address|alt text]]`, an empty label
+    marking it decorative.
+  - `packagebuild` is reserved, so any package can name a shared section banner
+    without declaring a dependency to reach it.
+  
+  The build reads art as file paths, so it refuses a tree written to this
+  specification. The specification is the target; the build is what runs today.
+- 60815eb: **A lint finding opens where it says it is** — Every path a content lint prints
+  is relative to the directory the command was run from, so one `content-build
+  lint` run reports every finding in the same shape and each one opens in an
+  editor, a CI annotation or a `$EDITOR +line` jump.
+  
+  - _Characters, icons, raw HTML and image directives_ report the note's path the
+    way the address and frontmatter rules beside them already do.
+- 7d79e70: **Content format** — A being's portrait is a picture in its prose, not a field.
+  It opens the note's `{#appearance}` section — the **lead image** — and
+  `data.portrait` is gone:
+  
+  ```markdown
+  # Appearance {#appearance}
+  
+  ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+  ```
+  
+  Nothing about that embed is special: it is an ordinary embedded image with an
+  ordinary directive, and the strictness is the convention that the portrait opens
+  the section, so every being note reads the same way. The section matters as well
+  as the order — `{#appearance}` is what becomes an actor's appearance, so a
+  picture above that heading reaches no document. An author can move it, caption it
+  or drop it like any other picture.
+  
+  Four art slots remain — `icon`, `tokenIcon`, `bgImage` and `banner` — each
+  naming art that a document field needs. An embed also takes the same `{…}`
+  directive an image does, so a float or a width applies to either.
+- d6d837c: **Content format** — An asset's address is derived from where its file sits.
+  Three roots, one per type — `assets/icons`, `assets/images` and `assets/audio` —
+  and any file with a matching extension anywhere beneath one is an asset of that
+  type, however deep. The filename is the shortcode, the
+  extension is not part of the address, and the directories in between are the
+  package's own business.
+  
+  A root's shortcodes are one flat namespace, so two files under one root sharing
+  a basename are a build error naming both. Across roots they are different
+  addresses: `icon-anvil` and `image-anvil` name different pictures for different
+  purposes.
+  
+  A font is not an asset and has no address. Nothing names a typeface the way a
+  note names a picture, and neither consumer of a font could use an address
+  anyway: a stylesheet wants a relative `url()` and the book wants a family name.
+  Fonts stay ordinary files a package ships and points a tool at.
+
+## 21.1.0
+
+### Minor Changes
+
+- 7577722: **Headings in the book**
+  
+  - A heading is set by its depth rather than every heading alike: a note's top-level heading opens large, keeps its underline and takes a clear run of space above it, and each level beneath is smaller and separated by space alone.
+  - Headings set in the sans face and in the case they were written in, so a section reads as words rather than as tracked capitals. A book that names no sans face still sets them in its book face, exactly as before.
+  - A parent section and the sections inside it can be told apart at a glance, without reading the words.
+- 57fee4c: **Infobox panels in the book**
+  
+  - Each panel is drawn as a closed box — a light border on all four sides over a tint a step below the paper — so a page carrying Profile, system and appearance panels reads as a stack of cards rather than a run of rules.
+  - Skill and equipment groups stand apart from one another, so a group that wraps onto a second line is no longer mistaken for the start of the next one.
+  
+  **Naming the systems**
+  
+  - The system panels are titled _Song of Heroic Lands_ and _HârnMaster 3_ in full, in the book and on the web, in place of the abbreviations.
+
+### Patch Changes
+
+- 705cdc8: **The book** — an entry's first paragraph sets like any other. A raised opening
+  letter is something a note asks for, not something the book decides on its
+  own, so nothing raises one.
+
 ## 21.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -100,6 +100,9 @@ icons: assets/icon-registry.yaml
 # conventional layout shown here.
 paths:
   content: assets/content
+  # The asset roots' parent: `icons/`, `images/` and `audio/` sit directly under
+  # it, and the content tree beside them.
+  assets: assets
   # Vendored foreign manifests, read by `links`. Inbound.
   manifests: assets/manifests
   # Where `manifest` writes this package's own. Outbound, and a build artifact.
@@ -1778,6 +1781,32 @@ asked for — a build that downloads silently is not reproducible and fails
 strangely offline. The cache is keyed by version, so changing the pinned version
 is a miss rather than a silent overwrite.
 
+### `packagebuild` needs no declaration
+
+package-build ships a set of images of its own — section banners chiefly — and a
+note reaches one without declaring anything:
+
+```yaml
+data:
+  banner: packagebuild-none-image-skillbnr
+```
+
+**There is nothing to declare and nothing to fetch.** package-build is an npm
+dependency of every consumer rather than a Foundry package, so there is no
+release archive behind the name and no reason to fetch one — the tree is already
+on disk under `node_modules/@heroiclands/package-build/assets/`. The records are
+walked from it on every load and join the index like any other package's, so a
+cold cache is not a failure mode here and every lookup stays one path.
+
+`packagebuild` is a **reserved** name: no repository may configure it as its
+`contentPackage`, and a configuration that tries is refused.
+
+**These addresses have no Foundry form.** Foundry installs no package for this
+one, so a resolver returns "no Foundry address" deliberately rather than
+deriving `modules/packagebuild/…`, which installs nowhere. That is not a
+limitation in practice: the only slot that names them is `banner`, which reaches
+no compiled document at all and is read by the website and the book.
+
 **A fetched catalogue is read one system at a time.** A dependency may ship a
 pack per system, and the two hold the same `(type, shortcode)` addresses with
 different data models — `skill:awar` is a real address in both vocabularies and
@@ -1956,17 +1985,59 @@ frontmatter spreads **242 distinct leaf paths** unevenly over **15 types**, from
 authoring. A format with a fixed column set would turn that authoring into a
 schema migration; a document format has no such problem.
 
-Two keys are **derived** rather than authored, and a note carrying either is an
+Three keys are **derived** rather than authored, and a note carrying one is an
 error rather than a silent overwrite:
 
 | Key       | What it holds                                                                                      |
 | --------- | -------------------------------------------------------------------------------------------------- |
 | `package` | The configured `contentPackage`. A note may not declare its own, and the expander reads the same.  |
 | `file`    | `path`, `folder` and `name` below the content root — the same `file.*` a content-table query uses. |
+| `asset`   | The file an asset record addresses. Present on an asset's record and on no note's.                 |
 
 The location is namespaced under `file` precisely because `folder` is real
 frontmatter on most notes; a record states both, and they mean different things.
 
+### A file is a record too
+
+The same pass walks the package's **asset roots** — `assets/icons`,
+`assets/images` and `assets/audio` — and emits one record per addressable file
+into the same index. There is no second artifact and no asset-specific emitter:
+a package whose tree holds only pictures publishes an ordinary content index
+that happens to hold only asset records.
+
+The filename is the shortcode, the root supplies the type, and the layout in
+between is the package's own business:
+
+```json
+{
+  "type": "icon",
+  "shortcode": "anvil",
+  "package": "sohl",
+  "address": { "canonical": "sohl-none-icon-anvil" },
+  "asset": {
+    "path": "icons/game-icons/lorc/anvil.svg",
+    "attribution": "Lorc",
+    "source": "http://lorcblog.blogspot.com",
+    "license": "CC-BY-3.0",
+    "notes": "From game-icons.net"
+  }
+}
+```
+
+An asset record carries no frontmatter, no anchors and no `foundry` block, and
+its `address` holds the canonical key and no page slug — a file declares nothing
+about itself, compiles into no document, and publishes no page. The `asset`
+block is what a reader tells the two shapes apart by.
+
+`path` is relative to the emitting package's own asset directory, so each
+consumer joins its own root onto it and resolves in one step. Provenance comes
+from a sibling `<filename.ext>.yaml` where one exists, and otherwise from the
+nearest `provenance.yaml` above the file, searching no higher than the type
+root. `docs/content-format.md` states the whole rule.
+
+Two files under one root sharing a basename are two claims on one address, and
+the build fails naming both.
+
 ### Every note's address, and every anchor it defines
 
 A record states the address a wikilink writes to reach the note, and every
@@ -2467,10 +2538,8 @@ alone — a scrolling page has no fixed viewport, so the website keeps one
 measure with a side rail.
 
 A note's `description:` sets as an epigraph between short rules under the
-plate, and the first paragraph of the prose opens on a raised capital. Both
-disappear rather than leave a shell: a note with no description has no
-epigraph, and a body opening on a link or a number keeps its own first
-character. The running foot carries the section's name, an ornament and the
+plate. It disappears rather than leave a shell: a note with no description has
+no epigraph. The running foot carries the section's name, an ornament and the
 folio.
 
 A table of **more than three columns** is given an explicit span rather than
@@ -2540,11 +2609,11 @@ pdf:
   out: build/dist # default
   front: # prose before the contents
     - prose/colophon.md
-  fonts:
+  fonts: # every key optional — the defaults below
     serif: Libertinus Serif
     sans: Libertinus Sans
     mono: DejaVu Sans Mono
-    path: assets/fonts # where to find them, beyond the system's
+    path: assets/fonts # faces of your own, searched as well as the shipped ones
   iconFonts: # icon family → the font carrying its glyphs
     fontawesome: assets/fonts/fa-solid-900.ttf
   binary: typst # when it is not simply `typst` on PATH
@@ -2553,6 +2622,39 @@ pdf:
 Nothing here is an address or a brand: the title, the front matter and the faces
 are the publishing repository's to choose, which is why they are configuration.
 
+### The faces come with the build, not with the machine
+
+All three defaults resolve on a machine that has none of them installed. The
+serif and the mono the defaults name are faces the compiler embeds; the sans is
+one the toolchain ships, under `assets/fonts`, along with the superfamily's own
+mono for a package that names it. The compile searches that directory, and
+`pdf.fonts.path` when a package names one, and **nothing the machine has
+installed** — `--font-path` and `--ignore-system-fonts` together — so the same
+source sets the same book everywhere, and a machine carrying its own copy of a
+named family does not quietly change what it prints.
+
+The default mono is the compiler's rather than the superfamily's because the
+superfamily's mono carries none of the dot-below and dot-above letters this
+corpus spells names with. A package whose fenced blocks stay inside what it does
+carry can name it instead, and the compiler reports nothing when a glyph is
+missing, so that is a claim to measure against the fences rather than assume.
+
+A face nothing resolves is a **finding** — the compiler says so, and a compile
+that says it still exits 0 and writes a book set in the fallback, which is the
+one way a wrong face reaches a reader unnoticed.
+
+Compiling an emitted `.typ` by hand takes the same two flags to set it the way
+the build does:
+
+```bash
+typst compile --ignore-system-fonts \
+  --font-path node_modules/@heroiclands/package-build/assets/fonts \
+  build/dist/the-book.typ
+```
+
+The shipped face is licensed under the SIL Open Font License, which travels with
+it.
+
 ### Typst is a binary, not a dependency
 
 The compiler is an external program, found on `PATH` or named by `pdf.binary`.

package/assets/fonts/libertinus/OFL.txt

@@ -0,0 +1,94 @@
+Copyright © 2012-2024 The Libertinus Project Authors,
+with Reserved Font Name "Linux Libertine", "Biolinum", "STIX Fonts".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/libertinus/provenance.yaml

@@ -0,0 +1,11 @@
+attribution: The Libertinus Project Authors
+source: https://github.com/alerque/libertinus/releases/tag/v7.051
+license: OFL-1.1
+notes: >-
+    Libertinus Sans in the three styles a heading can ask for, and Libertinus
+    Mono, which a package may name for its code spans. Taken unmodified from the
+    release's static/OTF directory; the licence text travels with them as
+    OFL.txt, as the OFL requires. The serif half of the superfamily is not here
+    because the compiler embeds it, and the remaining faces of the release —
+    Math, Display, Initials, Keyboard and the Semibold weights — are ones no
+    book sets.

package/assets/images/provenance.yaml

@@ -0,0 +1,4 @@
+attribution: Tom Rodriguez
+source: ""
+license: CC-BY-SA-4.0
+notes: ""

package/bin/content-build.mjs

@@ -969,6 +969,10 @@ function lintCommand() {
                 // so these are errors and they fail the run.
                 const images = lintContentImages(root, {
                     skipDirectories: config.skipDirectories,
+                    // Which packages this build can reach is configuration, and
+                    // an address naming one it cannot reaches a journal as a
+                    // path that resolves against nothing.
+                    config,
                 });
 
                 const findings = [
@@ -1250,6 +1254,7 @@ function linksCommand() {
                 const {
                     deadAnchors,
                     deadAddresses,
+                    deadEmbeds,
                     unlabelledLinks,
                     frontmatterLinks,
                     homepageLinks,
@@ -1271,12 +1276,15 @@ function linksCommand() {
                 // differently because the corrections differ. The wording comes
                 // from the shared table, so the checker cannot describe a
                 // defect differently from the build that also refuses it.
-                for (const d of [...deadAddresses, ...unlabelledLinks]) {
+                for (const d of [...deadAddresses, ...unlabelledLinks, ...deadEmbeds]) {
                     emitDiagnostic({
                         file: d.note.file,
                         ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
                         severity: "error",
-                        message: linkFindingMessage(d),
+                        // An embed's directive speaks the image vocabulary and
+                        // carries its own sentence; everything else is worded
+                        // by the shared table.
+                        message: d.message ?? linkFindingMessage(d),
                     });
                 }
                 for (const f of frontmatterLinks) {
@@ -1306,6 +1314,7 @@ function linksCommand() {
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
+                    deadEmbeds.length +
                     unlabelledLinks.length +
                     frontmatterLinks.length +
                     homepageLinks.length;
@@ -1315,8 +1324,9 @@ function linksCommand() {
                 } else {
                     log.info(
                         `${index.notes.length} notes: every link is a labelled ` +
-                            `address, every anchor link lands and every ` +
-                            `address resolves (${usedManifest.size} ` +
+                            `address, every embed names a file, every anchor ` +
+                            `link lands and every address resolves ` +
+                            `(${usedManifest.size} ` +
                             `cross-package reference(s) via manifest), no ` +
                             `wikilink in frontmatter, every homepage address ` +
                             `resolvable.`,
@@ -1576,7 +1586,11 @@ function siteCommand() {
                         file: e.file,
                         ...positionOfLiteral(readRawNote(e.file), e.link, e.occurrence),
                         severity: "error",
-                        message: linkFindingMessage(e),
+                        // An embed's directive speaks the image vocabulary
+                        // rather than the link one, and carries its own
+                        // sentence; everything else is worded by the shared
+                        // table.
+                        message: e.message ?? linkFindingMessage(e),
                     });
                 }
                 // An image whose pathname the site cannot resolve, located the