@heroiclands/package-build 21.1.0 → 22.0.0

package/docs/content-format.md

@@ -107,11 +107,11 @@ the key is **machinery**, steering a build or an interface rather than
 describing the subject, or it is an **image**, which rule 2 keeps out of the
 box:
 
-| key                          | why it carries no row                            |
-| ---------------------------- | ------------------------------------------------ |
-| `templatePriority`           | template machinery, not a fact about the subject |
-| `color`                      | sidebar machinery, not a fact about the subject  |
-| `portrait`, `img`, `overlay` | an image, which rule 2 keeps out of the box      |
+| key                      | why it carries no row                            |
+| ------------------------ | ------------------------------------------------ |
+| `templatePriority`       | template machinery, not a fact about the subject |
+| `color`                  | sidebar machinery, not a fact about the subject  |
+| the art slots, `overlay` | an image, which rule 2 keeps out of the box      |
 
 A field whose value is a **mapping** carries no row either — a governance
 ladder or a wall layout has no summary shape — and neither does one the note
@@ -196,6 +196,15 @@ A system that does not map the note's type gets **no box**. A box reading
 _Not available_ on every affiliation page would suggest a gap in the note when
 the truth is about the system's scope.
 
+Whether a document was produced is the compile's own answer rather than a
+reading of the frontmatter. The note's type must map to the system; the note
+must route to a pack of the document class that map names; and where **that
+pack declares a `system:`**, the note must carry that system's block, which is
+the same rule the pack itself compiles under. A pack declaring **no** system
+compiles every note it claims from `data:` and the field defaults, so a note
+with no block still produces a document and its box still carries content —
+which is the ordinary arrangement in a package built for one system.
+
 #### Four section layouts
 
 A section says how it is arranged, and a renderer switches on that and on a
@@ -506,7 +515,7 @@ type.
 | shared source           | → sohl                    | → hm3                        |
 | ----------------------- | ------------------------- | ---------------------------- |
 | `name.full`             | `name`                    | `name`                       |
-| `img`                   | `img`                     | `img`                        |
+| `data.icon`             | `img`                     | `img`                        |
 | `id`                    | `_id`                     | `_id`                        |
 | `packFolder`            | `folder`                  | `folder`                     |
 | `shortcode`             | `system.shortcode`        | NA                           |
@@ -520,23 +529,30 @@ no SoHL form, so its SoHL column is. Nothing else varies — which is why these
 rows are worth stating once: repeated sixteen times they buried the differences
 that matter.
 
-**`img` maps onto a document that has one, and not every type's does.** The row
-is shared because the key is legal on every note whatever its type, not because
-every document carries artwork: `doc`, `place`, `lore` and `scenario` compile
-into a JournalEntry, which has no image of any kind, and a `folder` compiles into
-a Foundry `Folder`, which has none either. A `homepage` compiles into no
-compendium document at all. On any of those the mapping has no destination, so an
-authored path is simply dropped — the note validates, the tree compiles, and the
-value goes nowhere.
+**`data.icon` maps onto a document that has one, and not every type's does.**
+The row is shared because the key is legal on every note whatever its type, not
+because every document carries artwork: `doc`, `place`, `lore` and `scenario`
+compile into a JournalEntry, which has no image of any kind, and a `folder`
+compiles into a Foundry `Folder`, which has none either. A `homepage` compiles
+into no compendium document at all. On any of those the mapping has no
+destination, so the resolved value is simply dropped — the note validates, the
+tree compiles, and the value goes nowhere.
+
+**What a note writes is an address; what a document carries is a path.**
+`data.icon` is a `WikiLink` defaulting to type `icon`, so a being writes
+`icon: anvil` and never a file name. The compiler resolves that address to the
+file the owning package ships and writes the resulting path into `img`. The two
+sides of this row are therefore in two different currencies, which is why the
+row reads `data.icon → img` rather than naming one thing twice.
 
 Since a dropped value looks exactly like a value never written, the frontmatter
-lint **reports it**: an `img:` (or `portrait:`) authored on a type whose passes
-emit neither is a warning naming the note and the key. A warning rather than an
-error, because the note still compiles correctly and the key is not certainly
-unwanted — a note's top level is the generated page's front matter as well, so a
-site template may read there what no document carries. `img: null` is never
-reported: that is the blessed way to say "this note names no art", and on a type
-with no art it is a true and harmless thing to say.
+lint **reports it**: an art key authored on a type whose passes emit none is a
+warning naming the note and the key. A warning rather than an error, because the
+note still compiles correctly and the key is not certainly unwanted — a note's
+top level is the generated page's front matter as well, so a site template may
+read there what no document carries. `null` is never reported: that is the
+blessed way to say "this note names no art", and on a type with no art it is a
+true and harmless thing to say.
 
 Which types those are is **not a list**. It is asked of the passes: a type routes
 to a document, a document to the pass that compiles it, and each pass declares
@@ -544,29 +560,85 @@ the art it writes (`emitsArt`). A second table of iconless types would be a tabl
 free to drift from what is actually emitted, which is the defect rather than the
 check.
 
-Actor types (`being`, `vehicle`) add one more:
+#### The four art slots
+
+A note declares the art its document needs, and every other image in it is
+inline. All four slots are ordinary `WikiLink` fields declaring a default type,
+exactly as `seat` declares `place` — a bare shortcode takes its type from the
+declaration, and qualification climbs the same short-form ladder every other
+link uses.
+
+| field       | default type | resolves into                | on                                        |
+| ----------- | ------------ | ---------------------------- | ----------------------------------------- |
+| `icon`      | `icon`       | `document.img`               | every Actor/Item type, and embedded items |
+| `tokenIcon` | `icon`       | `prototypeToken.texture.src` | Actor types                               |
+| `bgImage`   | `image`      | `background.src`             | map types                                 |
+| `banner`    | `image`      | the site hero image          | any note; not a Foundry field             |
+
+All four are authored under `data:`:
+
+```yaml
+data:
+  icon: anvil
+  banner: packagebuild-none-image-skillbnr
+```
+
+**Two of them are legal on _every_ note**, whatever its type. `data:` is a
+closed container and the per-type vocabularies below are the only lists there
+are, so a key legal everywhere is stated once here rather than repeated in
+twenty-five tables where the one that was mistyped would be the one nobody
+noticed:
+
+| shared `data` property | Values     | Description                                                          |
+| ---------------------- | ---------- | -------------------------------------------------------------------- |
+| `icon`                 | `WikiLink` | The document's profile art — an `icon` address, resolved into `img`. |
+| `banner`               | `WikiLink` | The page's hero image — an `image` address.                          |
 
-| shared source   | → sohl            | → hm3             |
-| --------------- | ----------------- | ----------------- |
-| `data.portrait` | `system.portrait` | `system.bioImage` |
+`icon` is legal everywhere because most types compile into a document that
+carries one; where a type's passes emit none, the lint says so and the value is
+left alone, because a page template may still read it. `banner` reaches no
+compiled document at all, and a page is what every note publishes.
 
-An actor carries `img` (its token art) and `portrait` (its sheet portrait)
-independently, which is why this is a row of its own rather than a second
-spelling of the one above. An Item has no second image, so the row applies to
-actor types alone. Note the asymmetry in where the two are authored: `img` stays
-at the note's top level and `portrait` moved under `data:`, because a note's
-token art is a fact about the _note as a published artefact_ while the portrait
-is a fact about the _subject_.
+The other two are narrower, and each type's own table names them: `tokenIcon`
+on the Actor types, `bgImage` on a map.
+
+**A portrait is not one of them.** A picture of the subject is a picture, so it
+is authored in the prose that describes the subject, as an ordinary embedded
+image — see [the lead image](#the-lead-image). A slot exists for art a
+_document field_ needs; nothing else earns one.
+
+**A reference carries no slashes and no extension.** That is what keeps it from
+being read as a file name, and it is checked: a value shaped like a pathname is
+an error naming the note and the key.
+
+`tokenIcon` unset defaults to `icon`. A token has to read at grid scale and when
+a map is zoomed out, so it is an `icon` rather than an `image`, and its fallback
+has to be `icon`-typed too.
+
+Actor types (`being`, `vehicle`) therefore add one row:
+
+| shared source    | → sohl                       | → hm3                        |
+| ---------------- | ---------------------------- | ---------------------------- |
+| `data.tokenIcon` | `prototypeToken.texture.src` | `prototypeToken.texture.src` |
+
+An actor's two pieces of art are two different questions. `data.icon` is the
+profile art — what a directory listing shows beside the name and what the sheet
+header carries. `data.tokenIcon` is what a token on the canvas wears. Both are
+wikilinks and both resolve the same way; only the destination differs. An Item
+has one piece of art, so this row applies to actor types alone.
 
 **A `data:` source is still read at the top level, for now.** `data:` did
-not invent the facts it holds — it gathered them out of the top level, where
-`portrait:` sat beside `img:` — so every key it collected has a **pre-`data:`
-spelling** that is read after the declared one and reported as retiring. Write
-`data.portrait`; a tree still on `portrait:` compiles to the identical document
-and gets a warning naming the line, until a later release removes the position.
-This is the shared level's counterpart to the in-block `<system>.<key>`
-retirement, and the two are separate: a note may have moved one and not the
-other.
+not invent the facts it holds — it gathered them out of the top level — so every
+key it collected has a **pre-`data:` spelling** that is read after the declared
+one and reported as retiring. This is the shared level's counterpart to the
+in-block `<system>.<key>` retirement, and the two are separate: a note may have
+moved one and not the other.
+
+**No image key is one of those.** A top-level `img:` is not authored at all:
+`data.icon` is a different key holding a different kind of value, and a note
+writing `img:` is naming a file where an address belongs. `portrait:` is not
+relocated either, at any level — a portrait is an embed in the body, and the
+key that used to declare one is not a key.
 
 **Two of the eight are Item-only in SoHL.** `actionDefs` and `notes` are declared
 on every SoHL Item subtype and on no SoHL Actor, so on a `being` or a `vehicle`
@@ -607,9 +679,9 @@ shipped tree, and the one piece every derived form is built from. A pathname
 that does not open `<package>/assets/` belongs to the package being compiled,
 and the whole of it is the suffix.
 
-```yaml
-img: images/beings/athlwvthrnd-portrait.webp # this package's
-img: sohl/assets/icons/noun/shield.svg # the sohl package's
+```markdown
+![A map of the Vale](images/maps/valeofthorns.webp) <!-- this package's -->
+![A shield](sohl/assets/icons/noun/shield.svg) <!-- the sohl package's -->
 ```
 
 The four forms, for a `thalorna` note (the `thalorna` package ships as the
@@ -676,39 +748,28 @@ whole `assets/` tree and the directory names inside it are its own business:
 `sohl-kethira-basic` keeps art under `assets/artwork/`, and `artwork/deity.webp`
 is that package's by the same rule that claims `icons/…` and `images/…`.
 
-**Every pathname a note carries follows it.** `img:` and `data.portrait:`; a
-map note's background, overlay, tile textures and ambient sounds; and the
-address of every image in a note's body.
-
-#### `banner:` addresses the CDN, not the Foundry install
+**Where a pathname is still authored, it follows this rule.** That is the
+address of an image in a note's body, and a map note's `overlay`. The art
+fields do not: `icon`, `tokenIcon`, `bgImage` and `banner` name
+addresses, and the path comes from the record the resolved address points at —
+which already carries the owning package, so there is nothing for a first
+segment to state.
 
-**`banner:` is a path, and it does not follow the rule above.** It is worth
-stating plainly, because the two fields look alike and a value written for one
-resolves somewhere else entirely under the other.
+#### `banner:` reaches no compiled document
 
-`banner:` never reaches a compiled document — searching a built `packs-json`
-tree for it turns up nothing. It is a top-level key, so it passes through to the
-generated page, and its only consumer is the Hugo theme, whose
-`partials/banner-url.html` applies its own rule: an absolute URL passes through,
-and **anything else is prefixed with `images/`** and joined onto
-`params.cdnBaseURL`. A `banner:` written to the package rule therefore resolves
-to a doubled path:
+`data.banner` is the page's hero image, and it is the one art slot with no
+Foundry destination: searching a built `packs-json` tree for it turns up
+nothing. It reaches the generated page and the book's section plates, and
+nothing else.
 
-```text
-banner: sohl/assets/images/banners/lore.webp
-      → <cdnBaseURL>/images/sohl/assets/images/banners/lore.webp
-```
-
-That can be made to work by mirroring the path on the CDN, and one consumer
-does exactly that — but it is not what the author meant.
+It is a `WikiLink` all the same, defaulting to type `image`, so a section note
+writes `banner: skillbnr` and a note borrowing another package's plate writes
+`banner: packagebuild-none-image-skillbnr`. The resolved record carries the
+owning package, and each surface joins the suffix onto its own root — the site
+onto `site.assets`, the book onto the directory it stages banners into.
 
-**The two are not reconciled, because they are not two spellings of one thing.**
-A pathname names a file a package ships, and four surfaces derive an address
-from it. `banner:` names a hero image on the site's own asset host, reaches no
-compiled document and no book, and is resolved by the theme rather than by this
-toolchain — `banner: none` is not even a target. Write a `banner:` relative to
-the CDN's `images/` root — `banners/lore.webp`, not `images/banners/lore.webp`
-and not a package-qualified pathname.
+**`banner: null` is how a note says it wants no plate.** It is a true statement
+on any type, and the frontmatter lint never reports it.
 
 #### The pack a note compiles into
 
@@ -1060,7 +1121,7 @@ free-form value decides the headings there.
 
 ### WikiLinks
 
-Twenty-seven fields in the tables below take a `WikiLink`, and a link is written
+Many fields in the tables below take a `WikiLink`, and a link is written
 `[[target]]` or `[[target|label]]`. The target is an **address**.
 
 #### The canonical address
@@ -1311,6 +1372,249 @@ Brackets belong in prose, where a link sits inside a sentence and needs marking
 off from the words around it. A frontmatter value has nothing to be marked off
 from.
 
+### Assets are types
+
+`icon`, `image` and `audio` are types in the type vocabulary, and an address
+reaches one exactly as it reaches a being or a skill. Their trees are
+the one thing about them that differs: they sit beside `content/` rather than
+inside it, because the thing a note is addressing is a file rather than a note.
+
+**Three roots, one per type.** The directory is named for what it holds and the
+type is named for what an address reaches, so the two differ by a letter and the
+mapping is declared rather than derived from the name:
+
+| root            | type    |
+| --------------- | ------- |
+| `assets/icons`  | `icon`  |
+| `assets/images` | `image` |
+| `assets/audio`  | `audio` |
+
+**A file's extension decides whether it is an asset at all**, and its root
+decides which type. Every image-extensioned file anywhere under `assets/icons`
+is an icon, and every audio-extensioned file under `assets/audio` is an audio
+asset, however deep it sits.
+
+That filter is load-bearing rather than tidy-minded: `provenance.yaml` files
+live **inside** these roots, at any level, and a walk that took every file would
+read attribution records as assets. A directory under `assets/` that is not one
+of the four holds no addressable asset — `assets/ui` is a package's own
+furniture, and nothing addresses it.
+
+**An asset type carries no system.** Its addresses keep the fourth segment, and
+it is always `none` — `sohl-none-icon-anvil`, never `sohl-icon-anvil` — so key
+parsing stays uniform across every type. The path shape is a property of the
+type rather than a test on a value.
+
+#### The filename is the shortcode
+
+```text
+assets/icons/game-icons/lorc/anvil.svg   →   <package>-none-icon-anvil
+assets/images/beings/creatures/drake.webp →  <package>-none-image-drake
+```
+
+**The extension is not part of the address**, and neither are the directories
+above the file. A root's shortcodes are one flat namespace however deeply the
+tree nests, so two files under one root sharing a basename are two claims on one
+address and a build error naming both. Across roots they are no such thing:
+`icon-anvil` and `image-anvil` are different addresses.
+
+Leaving the extension out is what makes a format change free. Changing an icon
+from SVG to WebP is dropping a different file in place, and no note changes;
+`abysdrksvg` and `abysdrkwebp` would be two addresses for one drake.
+
+**Beneath the root the structure is arbitrary, exactly as it is under
+`assets/content`.** A note's address does not depend on where its `.md` sits,
+and an asset's address does not depend on where its file sits within its root.
+Both trees are arranged for the people who maintain them —
+`icons/game-icons/<contributor>/`, `images/beings/creatures/` — and either can be
+rearranged wholesale without a single reference changing.
+
+**That freedom is the point.** Whoever maintains a tree organises it however
+makes sense to them — by contributor, by subject, by the source a set came from,
+by whatever the next thousand files want — and the build has no opinion. A
+layout that carried meaning would spend that freedom to buy nothing: moving a
+file would become a breaking change, and the arrangement would answer to the
+walk rather than to the person reading it.
+
+**The root itself is the exception, and only because an asset root is
+homogeneous.** `assets/content` is mixed: it holds beings, places, skills and
+the rest side by side, and each note declares its own `type:`, so no directory
+needs to. An asset root holds one type and nothing else — everything under
+`assets/icons` is an icon — which is what lets the root supply the type. It has
+to: a `.webp` carries no frontmatter and has nowhere to say what it is.
+
+So the two trees follow one rule about layout and differ on exactly one point:
+a note's type comes from the note, an asset's type comes from its root. That is
+also why the three roots are a closed list rather than a convention — a fourth
+directory under `assets/` declares nothing, so nothing in it is addressable.
+`assets/ui` and `assets/fonts` fall out of that rule rather than needing an
+exemption.
+
+**A shortcode is lowercase alphanumerics.** A filename that is not — a version
+string, a hyphen, a date stamp — cannot be addressed, and the build says so
+rather than inventing a shortcode for it.
+
+#### The asset record
+
+An asset reaches the content index as a record of its own — one line per
+addressable file, in the same JSON Lines index the notes publish into. It
+carries no frontmatter, no anchors and no `foundry` block: a file declares
+nothing about itself, compiles into no document, and publishes no page, so the
+`address` holds the canonical key and no page slug.
+
+| `asset` field | Source     | What it says                                                       |
+| ------------- | ---------- | ------------------------------------------------------------------ |
+| `path`        | the walk   | Where the file sits inside the emitting package's asset directory. |
+| `attribution` | provenance | Who made the file, or what tool generated it.                      |
+| `source`      | provenance | Where it came from — a URL, or a sentence.                         |
+| `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.       |
+| `notes`       | provenance | Anything else a person reading the attribution needs.              |
+
+Every field is present on every record, blank where nothing states one. A fixed
+shape is what lets a consumer read `asset.license` without first asking whether
+the package happened to record one.
+
+**`path` is what makes resolution one step.** The record is emitted by the
+package holding the bytes, so the path is that package's path and each consumer
+joins its own root onto it:
+
+| Consumer | `thalorna-none-image-thorn` resolves to                            |
+| -------- | ------------------------------------------------------------------ |
+| Web      | `<cdn base>/thalorna/images/beings/characters/thorn.webp`          |
+| Book     | `<asset base>/thalorna/images/beings/characters/thorn.webp`        |
+| Foundry  | `modules/sohl-thalorna/assets/images/beings/characters/thorn.webp` |
+
+Foundry names a **Foundry package id** rather than a content package, because
+the two are distinct — they are equal in the system only by coincidence, and in
+`sohl-thalorna` they differ.
+
+##### Where provenance comes from
+
+A `provenance.yaml` states `attribution`, `source`, `license` and `notes`, and
+nothing else: an unknown key is a finding rather than a silent drop, because
+`licence` beside `license` is otherwise an attribution record that looks
+complete and carries nothing.
+
+One address resolves its record in this order:
+
+1. A sibling `<filename.ext>.yaml`, which **replaces** an inherited record
+   wholesale rather than merging over it. A sidecar exists precisely because the
+   inherited answer is wrong for this one file, so carrying half of it forward
+   would make the record's meaning depend on a directory two levels up.
+2. Otherwise the nearest `provenance.yaml`, searching the file's own directory
+   and then its ancestors, **stopping at the type root**. A record above the root
+   would speak for trees it says nothing about.
+3. Otherwise nothing, and the provenance fields are blank. A package that
+   records no attribution is a fact to state, not a walk to fail.
+
+#### A font is not an asset
+
+`assets/fonts` is not a root, and a font has no address.
+
+**An asset type exists so a note can name a file and a package can substitute
+it.** Nothing about a font answers to either half. No note names a typeface —
+the art slots are `icon`, `tokenIcon`, `bgImage` and `banner` — and substituting
+one package's font for another's is not something anyone wants.
+
+**Neither consumer of a font can use an address.** A stylesheet names a file
+with `url()`, resolved relative to the stylesheet and never through the content
+index. The book names a _family_ — `#set text(font: "Libertinus Serif")` — and
+the typesetter matches that against a directory it is pointed at. One wants a
+relative path, the other a family name; an address serves neither.
+
+**And the model fits badly.** An address holds one file whose format is free to
+change, which suits a picture. A font family is a matrix of family, weight and
+style, and a filename already says which cell a file is — a shortcode would have
+to re-encode that, worse.
+
+So fonts stay ordinary files a package ships and points a tool at, and their
+licences are recorded where a person reads them rather than in an index.
+
+#### `icon` and `image` are two types, not one
+
+An icon has to stay coherent drawn into a 32×32 slot, which is why icons are
+SVG. An image is unbounded, expected to be large, and unreadable at that size.
+That is a fitness property of the asset itself, and one merged type would leave
+every consumer inferring the handling from the extension; two types let a guard
+assert it instead.
+
+So the two have **separate shortcode namespaces**. `icon-anvil` and
+`image-anvil` are different addresses for different purposes, and a rewrite rule
+reaches one without touching the other.
+
+**An asset address is its own name.** `image-thorn` is an image called `thorn`;
+any resemblance to `being-thorn` is coincidence, and nothing derives one from
+the other.
+
+#### `packagebuild` is a reserved package name
+
+package-build is an npm package rather than a system or a module, and it ships
+a set of images — section banners chiefly — that many packages draw on.
+Addressing them as `packagebuild-none-image-<shortcode>` lets a note reach one
+without declaring a dependency on some parent system or module it otherwise has
+no relationship with.
+
+**Its files reach the website and the book and no Foundry document.** Foundry
+installs no package of that name and no relationship can be declared with one,
+so `banner:` — the one art slot with no Foundry destination — is where a
+`packagebuild` address belongs. A body image naming one, written either way, is
+refused with the line and column it sits on.
+
+`packagebuild` is therefore **reserved** in the package registry: nothing may
+create a real package that collides with it, and its resolution is special-cased,
+because no installed directory sits behind the name.
+
+#### An embedded image is a wikilink
+
+```text
+![[address|label]]
+```
+
+There is no image grammar. An embed is the wikilink above, with `!` meaning
+_render it here_ rather than _link to it_, and the syntax supplying the default
+type the way a field declaration does — `image`. The short-form ladder, the
+package and system defaults, the lowercase rule, the ambiguity reporting and the
+findings vocabulary all apply unchanged.
+
+| written                        | means                                    |
+| ------------------------------ | ---------------------------------------- |
+| `![[anvil\|]]`                 | decorative — the common case             |
+| `![[anvil\|An anvil]]`         | alt text where it carries meaning        |
+| `![[anvil]]`                   | unlabelled, and a finding like any other |
+| `![[sohl-image-anvil\|Anvil]]` | qualified, reaching another package      |
+
+The parser distinguishes a missing label from an empty one, so _deliberately
+decorative_ and _not written_ differ without an exemption.
+
+**The label is the alt text, and it stays with the referrer.** One image serves
+many documents, and only the referrer knows what it means where it sits.
+
+**An embed reaches asset types only.** The syntax invites the broader reading —
+transclusion of an arbitrary note — so the restriction is a guard rather than a
+convention.
+
+**An embed takes the same directive an image does**, in the same place —
+immediately after the closing `]]`, with no space:
+
+```markdown
+![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[thalornamap|Map of Thalorna]]{.full-width}
+![[thalornamap|Map of Thalorna]]{.full-width, float: top-left}
+![[thalornamap|Map of Thalorna]]{float: top-left, .full-width}
+```
+
+**The same parser reads both**, so an embed takes a width class, a `float:`, or
+both together in either order, comma-separated — everything
+[an image's directive](#width-is-a-class-and-the-ordinary-width-carries-no-marker)
+takes and nothing beyond it. The width and position vocabularies are the ones
+above, and they are closed here for the same reason: a directive that is quietly
+ignored looks exactly like one that worked, and a directive holding a problem is
+not honoured in part either.
+
+**A being's portrait is one of these**, opening its `{#appearance}` section by
+convention rather than declared in a field — see
+[the lead image](#the-lead-image).
+
 ### What a note produces
 
 Note types fall into two groups, and only the first has a mapping table.
@@ -1402,7 +1706,7 @@ authored statement, three renderers, which is the single-sourcing every other
 part of this format follows.
 
 ```markdown
-![Brànwâal Dôrgaar](images/beings/branwldrgr-portrait.webp){float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
 
 ![Map of Thalorna](images/maps/thalorna.webp){.full-width}
 ```
@@ -1450,8 +1754,17 @@ not. The website and a Foundry journal get true CSS wrap from the same
 directive. Expect the same statement, not the same page.
 
 An image with no `float:` is an ordinary block in the flow, where it was
-written. A `.full-width` image is placed at the top of the page it falls on,
-since a block cannot leave the column it is set in.
+written. A `.full-width` image is set at the **top of a new page**: the book is
+set in two columns, only a float spans them both, and a float is placed where
+the page has room rather than where it was written — so the page breaks before
+the picture, and the prose that follows it runs below it on the same page. The
+picture can therefore never print above the prose that introduces it or after
+the prose that follows it, at the cost of the page before it ending short. A
+picture taller than the page takes a page of its own.
+
+A `.full-width` image that **also states a `float:`** is asking for a float and
+gets one, with no break before it. A float is placed where it fits, which may be
+the next page.
 
 ##### Both vocabularies are closed
 
@@ -1472,12 +1785,18 @@ a scheme of `http:` or `https:`, or none at all.
 
 ##### Where an address resolves
 
-An image's address follows the rule [`img:` follows](#an-asset-paths-first-segment-says-which-package-owns-it)
+An image's address follows [the pathname rule](#a-pathname-names-the-package-that-owns-the-file)
 — its first segment says which package owns the file — and each surface
 resolves it to what that surface serves:
 
 - **Foundry** is handed the path inside the install, so `images/map.webp`
-  reaches a journal page as `modules/<package>/assets/images/map.webp`.
+  reaches a journal page as `modules/<package>/assets/images/map.webp`. An
+  address with no such path — a package this build declares no relationship
+  with, or `packagebuild`, which Foundry installs nothing of — is **refused,
+  located by file, line and column**, and the build fails. Foundry is the one
+  surface a correctly written pathname can be dead on while the other two
+  resolve it, and a `src` that resolves against nothing looks exactly like an
+  address that worked.
 - **The book** is handed a copy of the file, staged out of this package's own
   asset tree into the build directory before the compiler runs. An address
   naming a file this package does not ship — another package's, or a URL —
@@ -1651,7 +1970,6 @@ The following H1 headers are treated specially:
 For JournalEntries, the following rules apply:
 
 - `# ... {#spoilers}`: The contents of this header go into a page which is viewable only by the GM (`CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE`).
-- The `portrait` frontmatter property will be added as a new JournalPage of type image with the name "Portrait" and anchor "portrait".
 
 **Archetype** is often used to describe a character in broad terms. These are often useful when determining whether a character matches a particular adventure. The list of character archetypes are:
 
@@ -1684,7 +2002,7 @@ Generates a living (or undead, or spirit) being.
 
 | `data` property             | Values                                         | Description                                                                                      |
 | --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `portrait`                  | `string`                                       | File path to the portrait image                                                                  |
+| `tokenIcon`                 | `WikiLink`                                     | What a token on the canvas wears — an `icon` address; defaults to `icon`                         |
 | `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                       |
 | `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — `[]` where none apply; `null` is an error. |
 | `occupation`                | `string`                                       | Name of the character's occupation                                                               |
@@ -1705,6 +2023,45 @@ Generates a living (or undead, or spirit) being.
 | `appearance.complexion`     | `string`                                       | Complexion                                                                                       |
 | `appearance.extra_features` | `string[]`                                     | Extra features                                                                                   |
 
+#### The lead image
+
+**A being's portrait is the first thing inside its `{#appearance}` section,
+always.**
+
+```markdown
+# Appearance {#appearance}
+
+![[<address>|<the being's full name>]]{float: top-left}
+```
+
+**Nothing about that embed is special.** It is an ordinary embedded image with
+an ordinary directive, and no pass treats it differently for sitting where it
+sits. What is strict is the convention: the portrait opens the appearance
+section, so a reader opening any being note finds the picture in the same place,
+and an author writing one never has to decide where it goes.
+
+**The section is the part that is not a convention.** `{#appearance}` is what
+becomes an actor's `system.appearance`, so a picture written above that heading
+is outside the section and reaches no document. The heading carries the anchor
+at **H1** — a deeper heading is not matched, and its whole section is extracted
+as empty rather than reported.
+
+The label is the being's full name. That is what a reader needs when the picture
+does not load, and what a screen reader announces in its place.
+
+**There is no `portrait` field**, at any level. A portrait is a picture of the
+subject, and a picture of the subject belongs in the prose that describes it —
+where an author can see it, move it, caption it or remove it, as with any other
+image. A field puts it somewhere only a template can reach, and every template
+then has to agree about where that is.
+
+Later images are ordinary images too — a second picture of the being, a coat of
+arms, a map of its holding — and they sit wherever the prose wants them,
+including in `{#dossier}`.
+
+**A being with no portrait writes no lead image.** There is no empty form and no
+placeholder.
+
 #### A being's embedded items
 
 `<system>.items` is a list, and each entry compiles into one embedded Item. An
@@ -1727,6 +2084,7 @@ sohl:
 | `model`  | yes      | The address of the item this entry is a copy of               |
 | `system` | no       | Values that override the model's                              |
 | `name`   | no       | A name of this entry's own, where it differs from the model's |
+| `data`   | no       | Art this entry names — see _An entry's art_ below             |
 
 **`type:` is not written beside a `model`.** The address already names the type,
 so a second statement of it is a place to be wrong, and it is refused.
@@ -1761,6 +2119,38 @@ things — and it could not say which package a template came from, so an addres
 resolved into a dependency only because no local pack claimed it and would have
 retargeted silently the day one did.
 
+#### An entry's art
+
+An entry is an item in every respect but where it is written, so it carries art
+by the two rules [an item note](#the-four-art-slots) does. It names an `icon`
+address under its own `data:`, and that resolves into the embedded document's
+`img`:
+
+```yaml
+sohl:
+  items:
+    - name: Quiver (leather)
+      type: miscgear
+      data:
+        icon: quiver
+      system:
+        shortcode: quiver
+```
+
+`icon` is the only slot an entry has. The other three belong to a note: two
+describe an Actor or a map, and `banner` is a page's hero image, which an
+embedded document has no page for.
+
+**Naming none is the common case, and it takes a default.** An entry copying a
+`model:` carries the catalogue item's art, and an entry copying nothing takes
+the default its type pairs in `itemBuilders` — the same default an item note of
+that type compiles with. An entry naming an address of its own overrides either.
+Writing `icon: ""` ships the document blank on purpose, and no default replaces
+it.
+
+**`data:` reaches no compiled document.** It is where a note names art, and a
+compiled Item has `img` instead; the container is read and goes no further.
+
 #### Identifying a being's embedded items
 
 Each entry in `sohl.items` compiles into one embedded Item, and its `_id` is
@@ -1827,15 +2217,15 @@ It will also generate a single JournalEntry located at the top level of the "jou
 
 Represents a conveyance able to hold goods and people moving from one place to another.
 
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `portrait`         | `string` | File path to the portrait image            |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
+| `data` property    | Values     | Description                                                              |
+| ------------------ | ---------- | ------------------------------------------------------------------------ |
+| `tokenIcon`        | `WikiLink` | What a token on the canvas wears — an `icon` address; defaults to `icon` |
+| `templatePriority` | `number`   | Template priority, _null_ = not a template                               |
 
 If `sohl` is present, this becomes a `vehicle` actor.
 
 It maps nothing beyond the shared rows above, actor row included: a vehicle
-carries a portrait and a template priority and no field of its own.
+carries a template priority and no field of its own.
 
 ### type: affiliation
 
@@ -2525,23 +2915,23 @@ are subTypes of one type rather than three types.
 
 The `data:` fields, of which three are required:
 
-| `data` property   | Values           | Description                                                                                                                                                    |
-| ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `img`             | `string`         | **Required.** The path to the map art. Becomes the level's `background.src` — what tokens stand on. Authored at the note's **top level**, not here — see below |
-| `dimensions`      | `[int, int]`     | **Required.** `[width, height]` in whole pixels, the art's own size                                                                                            |
-| `pxPerGrid`       | `integer`        | **Required.** Whole pixels per grid square; must match the art                                                                                                 |
-| `navName`         | `string`         | Short name for Foundry's scene navigation bar                                                                                                                  |
-| `levelName`       | `string`         | The name of the embedded level. Defaults to `Ground`                                                                                                           |
-| `backgroundColor` | `ColorHexValue`  | Shown where the art does not reach. Defaults to `#999999`                                                                                                      |
-| `overlay`         | `string`         | Path to **foreground** art                                                                                                                                     |
-| `walls`           | `WallSegment[]`  | List of wall segments                                                                                                                                          |
-| `doors`           | `Door[]`         | List of doors                                                                                                                                                  |
-| `lights`          | `Light[]`        | List of lights                                                                                                                                                 |
-| `tiles`           | `Tile[]`         | List of tiles                                                                                                                                                  |
-| `sounds`          | `Sound[]`        | List of sounds                                                                                                                                                 |
-| `regions`         | `SceneRegion[]`  | List of scene regions                                                                                                                                          |
-| `place`           | `WikiLink`       | The place this map depicts. Optional, because an encounter map depicts no named place — but that is the exception, and a map without one is a map of nowhere   |
-| `notes`           | `NoteLocation[]` | grid coordinates of note markers mapped to anchors in this document                                                                                            |
+| `data` property   | Values           | Description                                                                                                                                                  |
+| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bgImage`         | `WikiLink`       | **Required.** The map art — an `image` address. Becomes the level's `background.src`, what tokens stand on                                                   |
+| `dimensions`      | `[int, int]`     | **Required.** `[width, height]` in whole pixels, the art's own size                                                                                          |
+| `pxPerGrid`       | `integer`        | **Required.** Whole pixels per grid square; must match the art                                                                                               |
+| `navName`         | `string`         | Short name for Foundry's scene navigation bar                                                                                                                |
+| `levelName`       | `string`         | The name of the embedded level. Defaults to `Ground`                                                                                                         |
+| `backgroundColor` | `ColorHexValue`  | Shown where the art does not reach. Defaults to `#999999`                                                                                                    |
+| `overlay`         | `string`         | Path to **foreground** art                                                                                                                                   |
+| `walls`           | `WallSegment[]`  | List of wall segments                                                                                                                                        |
+| `doors`           | `Door[]`         | List of doors                                                                                                                                                |
+| `lights`          | `Light[]`        | List of lights                                                                                                                                               |
+| `tiles`           | `Tile[]`         | List of tiles, each naming its art in `image`                                                                                                                |
+| `sounds`          | `Sound[]`        | List of sounds, each naming its clip in `audio`                                                                                                              |
+| `regions`         | `SceneRegion[]`  | List of scene regions                                                                                                                                        |
+| `place`           | `WikiLink`       | The place this map depicts. Optional, because an encounter map depicts no named place — but that is the exception, and a map without one is a map of nowhere |
+| `notes`           | `NoteLocation[]` | grid coordinates of note markers mapped to anchors in this document                                                                                          |
 
 Everything else a Scene holds is **derived**, not authored: padding, grid type,
 grid distance and units, token vision and fog mode all come from the subType, and
@@ -2554,16 +2944,38 @@ one Level or it has no map at all, and nothing supplies one after the fact: the
 client-side `_preCreate` that would create it does not run during offline pack
 compilation, and the server-side migration shim is version-gated on
 `_stats.coreVersion`, so a pack stamped 14.x or later skips it entirely. The
-single Level is synthesised from `img`, `overlay`, `levelName` and
+single Level is synthesised from `bgImage`, `overlay`, `levelName` and
 `backgroundColor`.
 
-> **`img`, at the note's top level, as every other type's artwork is.** Art is
-> not system-specific — a Scene is a core Foundry document, and a second system
-> would want the identical art — so the field sits beside every other note's
-> `img` rather than inside a system block.
+> **`bgImage` is a `WikiLink` under `data:`, as every other type's artwork is.**
+> Art is not system-specific — a Scene is a core Foundry document, and a second
+> system would want the identical art — so the field sits under `data:` rather
+> than inside a system block.
 >
-> `image` is **not a key a map has**: in a `sohl:` block it is reported as
-> unknown, and either way the note is refused for the `img` it never declared.
+> **A map has no `img`.** `bgImage` is the only key naming a map's background,
+> and a note writing `img:` or `data.img:` is refused. The two are not
+> alternative spellings: `img` is a Foundry destination and no Scene has one.
+
+**Every art key inside a map is an address, and each is named for the type it
+reaches.** A map's geometry is authored in Foundry's own units, and its art is
+not authored in Foundry's own paths.
+
+| authored             | default type | emitted as                   |
+| -------------------- | ------------ | ---------------------------- |
+| `data.bgImage`       | `image`      | the level's `background.src` |
+| `tiles.<key>.image`  | `image`      | the tile's `texture.src`     |
+| `sounds.<key>.audio` | `audio`      | the `AmbientSound`'s `path`  |
+
+Naming each key for the type it references is what makes the default worth
+having: `audio:` reaches an `audio` address without a note ever writing the
+type segment. Where a tile places a glyph rather than artwork it qualifies —
+`image: sohl-none-icon-chest` — which is the ordinary short-form ladder rather
+than an exception to it.
+
+**The authored key and the emitted field differ where Foundry's name differs.**
+An `AmbientSound` stores its clip in `path`, and that is what the compiled
+document carries; the note writes `audio` because the note is naming an
+address, not filling in a Foundry field.
 
 **Two unit conventions, deliberately.** Geometry — walls, doors, lights, tiles,
 sounds, region shapes — is authored in **pixels**, Foundry's native storage,
@@ -2762,8 +3174,8 @@ rules describe it, and compiling one through this path would ship a macro whose
 body was a code block posted verbatim into chat. Chat macros as content would
 need an authoring convention of their own.
 
-The note's `img` is a content-relative path resolved the way every other note's
-is; a note that authors none takes Foundry's own `icons/svg/dice-target.svg`.
+The note's `data.icon` resolves the way every other note's does; a note that
+authors none takes Foundry's own `icons/svg/dice-target.svg`.
 
 ### type: bundle