@heroiclands/package-build 23.4.1 → 23.5.1

package/docs/project-setup.md

@@ -30,8 +30,7 @@ acme-bestiary/
 │   ├── config.json
 │   └── *.md                      # one per unreleased change
 ├── .github/
-│   ├── labels.yml                # the closed label registry
-│   ├── ISSUE_REPORTING.md        # §3 lists the same labels
+│   │   ├── ISSUE_REPORTING.md        # how issues are filed
 │   └── workflows/
 ├── assets/
 │   └── content/                  # authored Markdown notes
@@ -161,19 +160,18 @@ anything to remove.
 
 ### `lint:*` — the checks, one per question
 
-Seven checks, each answering one question and blind to what the others see.
+Six checks, each answering one question and blind to what the others see.
 They are separate scripts rather than one because a failing chain stops at its
 first failure, and knowing _which_ question failed is most of the diagnosis.
 
 ```json
-"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:labels lint:changelog",
+"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:changelog",
 "lint:format": "package-build format",
 "lint:markdown": "package-build markdown",
 "lint:markdown:fix": "package-build markdown --fix",
 "lint:addresses": "package-build lint",
 "lint:content-links": "package-build links",
 "lint:lang": "package-build lang check",
-"lint:labels": "package-build labels check",
 "lint:changelog": "package-build changelog check"
 ```
 
@@ -194,9 +192,6 @@ first failure, and knowing _which_ question failed is most of the diagnosis.
   `package-build lang coverage` and `package-build lang hardcoded`; a
   content-only package has nothing for those two to read, and each dies naming
   the glob that matched nothing rather than passing vacuously.
-- **`lint:labels`** — do `.github/labels.yml` and §3 of
-  `.github/ISSUE_REPORTING.md` still list the same labels? Neither derives from
-  the other, so nothing else notices when they drift.
 - **`lint:changelog`** — does every pending `.changeset/*.md` read like a
   release note rather than a pasted pull-request description? Passes
   trivially when nothing is pending: no pull request is required to carry a
@@ -499,46 +494,9 @@ tool:
 
 ## `.github/`
 
-Two files the toolchain reads, and they must agree.
-
-**`.github/labels.yml`** is the closed label registry — the machine-readable
-source of truth, synced to GitHub by the org-wide `labels` action. A label on
-GitHub that is not listed there is deleted on the next sync, which is what makes
-the set closed and why nothing invents one.
-
-```yaml
-- name: documentation
-  color: "0075ca"
-  description: Documentation about this repository — README, process, authoring guides.
-
-- name: devops
-  color: "e07b31"
-  description: Build, tooling, CI, release, repo config.
-```
-
-**`.github/ISSUE_REPORTING.md`** §3 is the same list in prose, for a human
-filing an issue. `package-build labels check` compares the two and fails when
-they disagree:
-
-```console
-$ npx package-build labels check
-package-build: registry and §3 agree (2 labels).
-```
-
-Neither file derives from the other, so this check is the only thing standing
-between them and a silent divergence. Editing the registry means editing both.
-
-Labels are **subject matter only**. Work shape — bug, feature, epic, task, spike
-— is an issue _type_, shared across the organization, so there is no `bug` label
-and filtering on one returns nothing.
-
-Neither file exists in a fresh repository, and `labels check` says so rather
-than passing vacuously:
-
-```console
-$ npx package-build labels check
-package-build: labels check: .github/labels.yml does not exist.
-```
+**`.github/ISSUE_REPORTING.md`** says how issues are filed. Labels are
+organisation-level and defined in `HeroicLands/.github`, so the repository
+carries no label registry of its own.
 
 `.github/workflows/` then carries the repository's own CI. The org-wide
 `HeroicLands/.github` repository supplies the shared composite actions those
@@ -549,17 +507,16 @@ site-deploy workflow, so a fix to any of them reaches every repository at once.
 
 A summary, because "where does this come from" is the question that recurs.
 
-| Read                                               | By                                                                                                        |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `package.json`                                     | The Foundry package id, the version, the release addresses; the site's `baseURL`, description and author. |
-| `package-build.config.yaml`                        | Everything else about the build.                                                                          |
-| `assets/content/**/*.md`                           | Every content command.                                                                                    |
-| `.gitignore`                                       | `package-build format`, `package-build markdown`.                                                         |
-| `.prettierignore`                                  | `package-build format`.                                                                                   |
-| `.github/labels.yml`, `.github/ISSUE_REPORTING.md` | `package-build labels check`.                                                                             |
-| `lang/*.json`                                      | `package-build lang`.                                                                                     |
-| `.env.local`                                       | `package-build deploy`.                                                                                   |
-| `.github/workflows/build.yml`                      | The `pre-push` hook, for its step list.                                                                   |
+| Read                          | By                                                                                                        |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `package.json`                | The Foundry package id, the version, the release addresses; the site's `baseURL`, description and author. |
+| `package-build.config.yaml`   | Everything else about the build.                                                                          |
+| `assets/content/**/*.md`      | Every content command.                                                                                    |
+| `.gitignore`                  | `package-build format`, `package-build markdown`.                                                         |
+| `.prettierignore`             | `package-build format`.                                                                                   |
+| `lang/*.json`                 | `package-build lang`.                                                                                     |
+| `.env.local`                  | `package-build deploy`.                                                                                   |
+| `.github/workflows/build.yml` | The `pre-push` hook, for its step list.                                                                   |
 
 Everything written goes under `build/`. Nothing the toolchain generates is
 committed.

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
 
@@ -4419,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               |
@@ -4451,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
@@ -4491,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                                                                           |
@@ -4541,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`