@heroiclands/package-build 23.4.0 → 23.5.0

package/docs/reference/format-details.md

@@ -917,7 +917,9 @@ of ownership** and every surface derives its own address from it.
 
 **The first segment names the package, when an `assets/` follows it.**
 Everything after that `assets/` is the _suffix_ — the path inside the package's
-shipped tree, and the one piece every derived form is built from. A pathname
+`assets/` directory, and the one piece every derived form is built from. A
+suffix under `icons/` or `images/` reaches Foundry and the website in the
+deployed layout, by type root and basename alone. A pathname
 that does not open `<package>/assets/` belongs to the package being compiled,
 and the whole of it is the suffix.
 
@@ -931,7 +933,7 @@ ships as the Foundry module `harn-ensemble`) writing `images/map.webp`:
 
 | Surface     | Address                                                    |
 | ----------- | ---------------------------------------------------------- |
-| **Foundry** | `modules/harn-ensemble/assets/images/map.webp`             |
+| **Foundry** | `modules/harn-ensemble/images/map.webp`                    |
 | **Local**   | `assets/images/map.webp`                                   |
 | **Web**     | `https://cdn.heroiclands.org/harnensemble/images/map.webp` |
 | **Book**    | `assets/images/map.webp`, staged beside the Typst source   |
@@ -941,9 +943,9 @@ system ships and this repository does not hold:
 
 | Surface     | Address                                                       |
 | ----------- | ------------------------------------------------------------- |
-| **Foundry** | `systems/sohl/assets/icons/noun/shieldnn.svg`                 |
+| **Foundry** | `systems/sohl/icons/shieldnn.svg`                             |
 | **Local**   | `assets/icons/noun/shieldnn.svg`, in the `sohl` repository    |
-| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shieldnn.svg`    |
+| **Web**     | `https://cdn.heroiclands.org/sohl/icons/shieldnn.svg`         |
 | **Book**    | not carried, unless a declared replacement carries it instead |
 
 **The content package name and Foundry id are separate values.**
@@ -1863,7 +1865,7 @@ nothing about itself, compiles into no document, and publishes no page, so the
 | `path`        | the walk   | Where the file sits inside the emitting package's asset directory.                                                                                                                                                                   |
 | `attribution` | provenance | The person holding the rights, to whom attribution is legally due.                                                                                                                                                                   |
 | `source`      | provenance | Where it came from — a URL, or a sentence.                                                                                                                                                                                           |
-| `ai`          | provenance | Whether the file is machine-generated — strictly the YAML boolean `true` or `false`; any other value is a finding, never a stringified record. Unstated resolves to `false`.                                                         |
+| `ai`          | provenance | Whether the file is machine-generated — strictly the YAML boolean `true` or `false`; any other value is a finding, never a stringified record. Required: a record that leaves it out is a finding, never read as `false`.            |
 | `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.                                                                                                                                                                         |
 | `notes`       | provenance | Anything else a person reading the attribution needs.                                                                                                                                                                                |
 | `role`        | provenance | What the picture is for — `portrait`, `emblem`, `banner`, `plate` or `map`. Absent for an ordinary picture; a value outside that set is a finding. The `image` type only — a value on an `icon` address is a finding and is dropped. |
@@ -1874,17 +1876,21 @@ 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/thalorna/assets/images/beings/characters/thorn.webp` |
-
-Foundry paths use the **Foundry package id**. The two values are both `thalorna`
+**`path` is the source path.** The record is emitted by the package holding
+the bytes, so the path is where the file sits in that package's repository. The
+book stages from it; Foundry and the website serve the **deployed layout**, the
+type root and the basename alone:
+
+| Consumer | `thalorna-none-image-thorn` resolves to                     |
+| -------- | ----------------------------------------------------------- |
+| Web      | `<cdn base>/thalorna/images/thorn.webp`                     |
+| Book     | `<asset base>/thalorna/images/beings/characters/thorn.webp` |
+| Foundry  | `modules/thalorna/images/thorn.webp`                        |
+
+Foundry and the website serve a picture under `icons/` or `images/` flat, by
+type root and basename — see [what a package ships](#what-a-package-ships);
+every other file keeps its path under `assets/`, and the local and book forms
+keep the repository's arrangement. Foundry paths use the **Foundry package id**. The two values are both `thalorna`
 for this image; `harnensemble` content uses `harn-ensemble` in its Foundry paths.
 
 ##### What a role declares
@@ -1987,19 +1993,131 @@ One address resolves its record in this order:
 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.
+3. Otherwise nothing, and that is a **finding at the file**: every asset is
+   covered by a record, because the stage decides from the record whether the
+   file ships.
+
+Resolution is per file. One directory routinely holds files its own
+`provenance.yaml` covers beside files a sidecar answers for, and each is
+resolved on its own.
 
 **The nearest record is the whole answer.** It is never merged with the one
 above it, so a record states every key it means to claim — which is what lets a
 reader open one file and know what the tree beneath it carries, instead of
 resolving a chain by hand.
 
-That is also why `attribution` and `license` are **required in any record that
-exists**: a key left out is not inherited from above, it is simply absent, so a
-record stating neither leaves every file it covers with no rights holder and no
-terms. Omitting one is a finding. `source`, `ai`, `notes` and `role` stay optional,
-because a blank is a truthful answer for each of them.
+That is also why `attribution`, `license` and `ai` are **required in every
+record**: a key left out is not inherited from above, it is simply absent, so a
+record stating none leaves every file it covers with no rights holder, no terms,
+or no statement of whether a machine made it. Omitting one is a finding at the
+record, which an empty file is held to as well. An unstated `ai` is never read as
+`false`. `source`, `notes` and `role` stay optional, because a blank is a
+truthful answer for each of them.
+
+##### What a package ships
+
+The repository keeps every picture; the Foundry package carries a filtered copy.
+`package-build assets` stages a file from `assets/icons/` or `assets/images/`
+only when its resolved record says `ai: false` **and** its `license` is one of:
+
+| Licence                      | Spelled                      |
+| ---------------------------- | ---------------------------- |
+| Public domain                | `LicenseRef-PublicDomain`    |
+| Creative Commons Zero        | `CC0-1.0`, or `CC0`          |
+| Creative Commons Attribution | `CC-BY-3.0`, `CC-BY-4.0`     |
+| Attribution-ShareAlike       | `CC-BY-SA-4.0`               |
+| Noun Project Pro             | `LicenseRef-NounProject-Pro` |
+
+The spelling is matched exactly; nothing is normalised. A package adds licences
+to this list with `packageBuild.shippingLicenses`, and ships under the list
+together with its additions. `ai: true` is never shipped, whatever the
+additions say. Audio is not filtered
+and not laid out flat — a package stages it with an ordinary
+`packageBuild.assets` row.
+
+**The deployed layout is flat.** A shipped picture sits at the package root as
+`icons/<basename>` or `images/<basename>`, whatever directories hold it in the
+repository. The root is the type and the basename is the shortcode with its
+extension, so the path follows from the address alone, and a root's shortcodes
+being one namespace is what keeps the flattening collision-free. The same
+layout serves Foundry (`modules/thalorna/images/thorn.webp`), the website's CDN
+(`<cdn base>/thalorna/images/thorn.webp`), and every location a world copies
+the pictures to.
+
+**The package's asset set**, `asset-sets/default.json` under the package
+root, lists what it ships. The name is fixed, so a world always finds the
+package's own set there:
+
+```json
+{
+  "name": "Thalorna — shipped art",
+  "package": "thalorna",
+  "assets": [
+    {
+      "address": "thalorna-none-icon-anvil",
+      "source": "../icons/anvil.svg",
+      "target": "icons/anvil.svg",
+      "size": 412
+    }
+  ]
+}
+```
+
+| Key       | What it says                                                                                                                                                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`    | The set's display name: the package's manifest title with ` — shipped art` appended, or the content package without a title.                                                                    |
+| `package` | The content package — the addresses' first segment, not the Foundry id.                                                                                                                         |
+| `assets`  | One entry per file, in `target` order.                                                                                                                                                          |
+| `address` | The file's canonical address.                                                                                                                                                                   |
+| `target`  | The file's path relative to the location's root, in the deployed layout, extension included.                                                                                                    |
+| `source`  | Where the file is fetched from, resolved against the URL of the set file holding it — `new URL(source, setUrl)`. The package's own set sits in `asset-sets/`, so its `source` is `../<target>`. |
+| `size`    | The staged file's size in bytes.                                                                                                                                                                |
+
+`target` is never the record's source `path`. Each release attaches
+`icons.zip` and `images.zip` beside the package archive: one picture root of
+the stage each, with `asset-sets/default.json`, for a GM placing the files by
+hand.
+
+##### Every reference states its address
+
+A compiled document names a picture by its Foundry path, and beside each
+reference it states the picture's canonical address, so a world can rebuild the
+path for wherever it keeps the file:
+
+- **HTML.** Each `<img>` whose `src` names an asset carries
+  `data-asset="<address>"`.
+- **Path fields.** The address sits in `flags.<system>.assets` on the document
+  holding the field, as nested objects mirroring the field's path — never a
+  dotted key, which Foundry's `expandObject` splits. `<system>` is the system
+  the document is compiled for, its `_stats.systemId`.
+
+| Document                                    | Flag on                | Keys          |
+| ------------------------------------------- | ---------------------- | ------------- |
+| Actor, Item, ActiveEffect, Macro, RollTable | the document           | `img`         |
+| Actor token art                             | `prototypeToken.flags` | `texture.src` |
+| Table result                                | the result             | `img`         |
+| Journal image page                          | the page               | `src`         |
+
+```json
+"img": "modules/thalorna/icons/anvil.svg",
+"flags": { "sohl": { "assets": { "img": "thalorna-none-icon-anvil" } } },
+"prototypeToken": {
+    "texture": { "src": "modules/thalorna/icons/anvil.svg" },
+    "flags": { "sohl": { "assets": { "texture": { "src": "thalorna-none-icon-anvil" } } } }
+}
+```
+
+Embedded documents — an actor's items and effects, a journal's pages, an
+Adventure's contents — each carry their own. A path or an `<img>` naming no
+asset is left as it is.
+
+**A picture the package does not ship draws a stand-in.** A reference to an
+excluded picture compiles to its package's own stand-in,
+`<package>-none-icon-missing` or `<package>-none-image-missing` — a picture
+under `icons/` or `images/` named `missing`, human-made and licensed to ship —
+and keeps the excluded picture's address in its flag or `data-asset`. A
+package that leaves out a picture a note references and ships no stand-in of
+that type fails the build with an error at the referencing note.
 
 ##### A declared replacement resolves first
 
@@ -3688,6 +3806,13 @@ tattoo, scar or brand may show gear or a gesture, as in `a tattoo of a knight's
 helmet`, and stands; the voice, impression, handedness, sterility and age rules
 hold even for a mark.
 
+A condition is a feature only through what it shows. Its visible sign is a mark
+— `trembling hands`, `one eye missing`, `a withered left arm` — and a skin sign
+the complexion words cover goes in `complexion`, so healed pox is `pockmarked`
+and acne scarring `scarred`. A condition with no visible sign, such as epilepsy,
+haemophilia or a parasite, stays in the being's prose and is not an appearance
+fact at all.
+
 ```yaml
 data:
   gender: female
@@ -3735,29 +3860,44 @@ The words, and what each means:
 | `blue`       | Blue       | Unmixed blue, from pale ice to deep sea.                                           |
 | `brown`      | Brown      | Mid-brown, the iris pattern still legible in ordinary light.                       |
 | `dark_brown` | Dark Brown | Brown so deep the iris barely separates from the pupil.                            |
+| `gold`       | Gold       | A bright metallic yellow iris, brighter and colder than `amber`.                   |
 | `grey`       | Grey       | Grey or grey-blue, cool and without green.                                         |
 | `green`      | Green      | Green dominant, with no brown ring worth naming.                                   |
 | `hazel`      | Hazel      | Brown and green together, often shifting with the light; the commonest mixed eye.  |
+| `red`        | Red        | An iris that is red, as in some undead and elder folk.                             |
+| `pink`       | Pink       | A pale pink or rose iris, as in albinism.                                          |
+| `silver`     | Silver     | A grey iris with a bright metallic sheen rather than a dull cast.                  |
 | `violet`     | Violet     | The pink-violet of an iris carrying no pigment.                                    |
+| `white`      | White      | An iris white or near-white, so that the eye reads pale throughout.                |
+| `yellow`     | Yellow     | A pale, flat yellow iris without the warmth of `amber`.                            |
 
 **`data.appearance.hair_color`**
 
-| Word               | Label            | Meaning                                                                   |
-| ------------------ | ---------------- | ------------------------------------------------------------------------- |
-| `auburn`           | Auburn           | Red-brown with the red dominant.                                          |
-| `black`            | Black            | True black, with no brown cast in sunlight.                               |
-| `blonde`           | Blonde           | Light yellow, from near-white to wheat.                                   |
-| `brown`            | Brown            | Mid-brown, neither dark nor reddish.                                      |
-| `chestnut`         | Chestnut         | Mid-brown with a red cast, the brown dominant — between brown and auburn. |
-| `dark_blonde`      | Dark Blonde      | Blonde darkened towards light brown.                                      |
-| `dark_brown`       | Dark Brown       | Brown approaching black, still brown in sunlight.                         |
-| `grey`             | Grey             | Grey throughout, with nothing of the original colour left to read.        |
-| `greying_black`    | Greying Black    | Black still dominant, grey coming in.                                     |
-| `greying_brown`    | Greying Brown    | Brown still dominant, grey coming in.                                     |
-| `red`              | Red              | Ginger or copper, the red unmixed with brown.                             |
-| `silver`           | Silver           | Grey with a bright metallic sheen rather than a dull cast.                |
-| `strawberry_blond` | Strawberry Blond | Pale red-gold: blonde with a red cast, lighter than red.                  |
-| `white`            | White            | Wholly white, whether from age or from carrying no pigment.               |
+| Word                       | Label                    | Meaning                                                                                                                      |
+| -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `auburn`                   | Auburn                   | Red-brown with the red dominant.                                                                                             |
+| `black`                    | Black                    | True black, with no brown cast in sunlight.                                                                                  |
+| `blonde`                   | Blonde                   | Light yellow, from near-white to wheat.                                                                                      |
+| `brown`                    | Brown                    | Mid-brown, neither dark nor reddish.                                                                                         |
+| `chestnut`                 | Chestnut                 | Mid-brown with a red cast, the brown dominant — between brown and auburn.                                                    |
+| `dark_blonde`              | Dark Blonde              | Blonde darkened towards light brown.                                                                                         |
+| `dark_brown`               | Dark Brown               | Brown approaching black, still brown in sunlight.                                                                            |
+| `grey`                     | Grey                     | Grey throughout, with nothing of the original colour left to read.                                                           |
+| `greying_auburn`           | Greying Auburn           | Auburn still dominant, grey coming in.                                                                                       |
+| `greying_black`            | Greying Black            | Black still dominant, grey coming in.                                                                                        |
+| `greying_blonde`           | Greying Blonde           | Blonde still dominant, grey coming in.                                                                                       |
+| `greying_brown`            | Greying Brown            | Brown still dominant, grey coming in.                                                                                        |
+| `greying_chestnut`         | Greying Chestnut         | Chestnut still dominant, grey coming in.                                                                                     |
+| `greying_dark_blonde`      | Greying Dark Blonde      | Dark Blonde still dominant, grey coming in.                                                                                  |
+| `greying_dark_brown`       | Greying Dark Brown       | Dark Brown still dominant, grey coming in.                                                                                   |
+| `greying_light_brown`      | Greying Light Brown      | Light Brown still dominant, grey coming in.                                                                                  |
+| `light_brown`              | Light Brown              | Brown lightened toward dark blonde: paler than `brown`, darker than `dark_blonde`.                                           |
+| `greying_red`              | Greying Red              | Red still dominant, grey coming in.                                                                                          |
+| `greying_strawberry_blond` | Greying Strawberry Blond | Strawberry Blond still dominant, grey coming in.                                                                             |
+| `red`                      | Red                      | Ginger or copper, the red unmixed with brown.                                                                                |
+| `silver`                   | Silver                   | A bright metallic pale between white and grey: the silver of great age, or the natural silver some elder folk are born with. |
+| `strawberry_blond`         | Strawberry Blond         | Pale red-gold: blonde with a red cast, lighter than red.                                                                     |
+| `white`                    | White                    | Wholly white, whether from age or from carrying no pigment.                                                                  |
 
 **`data.appearance.skin_color`**
 
@@ -4397,18 +4537,19 @@ a propertied or senatorial order supplies nearly everyone who holds them, it is
 **Democracy**.
 
 The distinction is not academic: it is the difference between a ladder whose top
-rungs are a class one is born or bought into, and one whose top rungs are an
-office one is voted into and then vacates. A republic's ladder therefore carries
-**both** — the civic status (Citizen) and the standing in the governing body above
-it (Senator) — because a citizen is not a member of the Senate, and conflating the
-two is the commonest way to get a non-monarchy wrong.
+rungs are a class one is born or bought into, and a body whose highest posts are
+offices one is voted into and then vacates. A republic's ladder therefore carries
+**both** standings — the civic status (Citizen) and the standing in the governing
+body above it (Senator) — because a citizen is not a member of the Senate, and
+conflating the two is the commonest way to get a non-monarchy wrong. The
+magistracies held for a term are offices, not rungs.
 
 **Rank**
 Definition of a level within the organization (e.g., Priest, Layperson, Member, Gang Leader, Master, etc.)
 
 | Property      | Required | Values    | Description                                                                                                                          |
 | ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `level`       | yes      | integer   | The ranking within the affiliation, increasing values starting with 1, 0 indicates intentional exclusion (expulsion/excommunication) |
+| `level`       | yes      | integer   | The ranking within the affiliation: 0 those it excludes (expelled, excommunicated), 1 its ordinary members, higher values above them |
 | `title`       | yes      | string    | Title associated with the Rank                                                                                                       |
 | `description` | yes      | string    | Description of the Rank                                                                                                              |
 | `lore`        | no       | `Address` | The standing this rank _is_ — a `lore` note of subType `law`, shared with every other body that confers the same thing               |
@@ -4429,11 +4570,37 @@ moving two lines renames the standing. A body that confers two titles at one
 standing writes them as one rung — `title: Knight or Dame` — or gives each its
 own level.
 
+**Every ladder has rung 0 and rung 1.** Level 1 is the ordinary member, and level
+0 names those the body excludes. A body that can name its members can name those
+it shuts out, whether or not it ever does, so an affiliation whose
+`governance.ranks` lacks either is an **error** at the `ranks` key, as is one
+with no ladder at all. The level-0 title is the body's own word for the excluded
+— Outlaw, Apostate, Níðing — never a generic "Excluded".
+
+Those two rungs are the minimum. Add rungs above level 1 only where the body
+truly has them, generally no more than five. **A rung is a standing, what a member
+is; an office is a post, what a member does.** Leadership is normally an office
+held by the top rank rather than a rank above it, and a rank never falls when an
+office is left: a bishop stays a bishop after being Presiding Bishop.
+
+```yaml
+data:
+  governance:
+    ranks:
+      - { level: 0, title: Apostate, description: Put out of the communion. }
+      - { level: 1, title: Layman, description: A baptised member of the faith. }
+      - { level: 2, title: Priest, description: Ordained to serve a parish. }
+      - { level: 3, title: Bishop, description: Consecrated to oversee a diocese. }
+    offices:
+      Presiding Bishop: Chairs the synod of bishops for a term.
+```
+
 ```yaml
 data:
   governance:
     ranks:
       - { level: 0, title: Vrystrith, description: Kinless and owed nothing. }
+      - { level: 1, title: Kinsman, description: Born or adopted into a household. }
       - { level: 4, title: Fródrád, description: A householder whose word carries. }
       - level: 5
         title: Hárár
@@ -4469,7 +4636,7 @@ rank names the standing, and the standing says.
 | `symbol`                                        | `string`                                           | Its emblem in words: a feather atop a golden scale, a chisel carving a star                    |
 | `governance.model`                              | `GovernanceModel`                                  | Type of government structure, if applicable                                                    |
 | `governance.summary`                            | `string`                                           | summary of the governance situation                                                            |
-| `governance.ranks`                              | `Rank[]`                                           | The ranks available to members of the affiliation                                              |
+| `governance.ranks`                              | `Rank[]`                                           | The ranks the affiliation confers; level 0 and level 1 are required                            |
 | `governance.ranks[].level`                      | `integer`, required                                | The rung's position on this body's ladder; a member's `rank` names it                          |
 | `governance.ranks[].title`                      | `string`, required                                 | What the standing is called                                                                    |
 | `governance.ranks[].description`                | `string`, required                                 | What the standing is                                                                           |
@@ -4519,14 +4686,15 @@ the ranks and offices that exist, and a membership names which of them it holds.
 **Rank is the organisation's, not the member's.** A bare `level: 4` on a
 membership says nothing on its own; it means _Knight_ only because the polity
 declared that rung. So the ladder is authored once, on the body that confers it,
-and a member's rank is an index into it. Level 0 is reserved for the excluded —
-outlawed, expelled, excommunicated — which is a standing the organisation still
-recognises, and so still has to define.
+and a member's rank is an index into it. Level 0 is the excluded — outlawed,
+expelled, excommunicated — which is a standing the organisation still
+recognises, and so every ladder defines it beside level 1.
 
 **Offices are named, not ranked.** A Chancellor and a Marshal are both great
 officers and neither is above the other, so an office is a key with a
 description rather than a rung — and a being may hold an office at any rank, or a
-rank with no office at all.
+rank with no office at all. The head of a body is usually an office of this kind,
+held by a member of the top rank, who keeps that rank when the term ends.
 
 An office may remain a string description or declare a `description` and a
 `holders` list. Each holder names a `being` Address; optional `start` and `end`