@heroiclands/package-build 23.4.1 → 23.5.1

package/docs/authoring/assets.md

@@ -26,16 +26,31 @@ The embed's label is alternative text. `![[icon-harbor|]]` is decorative. `size=
 
 ## Ownership and source records
 
-Record provenance for the assets you ship. Put `provenance.yaml` in an asset directory to describe files there and below, or put a YAML sidecar beside one asset to give that file its own record. A sidecar takes precedence over a directory record for that asset. An asset with no record still enters the index with blank provenance fields. Keep attribution with the authored asset so movement through the tree does not lose its source or license. See the [asset record reference](../reference/format-details.md#the-asset-record) for the accepted keys, inheritance, and examples.
+Every asset is covered by a provenance record. Put `provenance.yaml` in an asset directory to describe files there and below, or put a YAML sidecar named for the whole filename — `anvil.svg.yaml` — beside one asset to give that file its own record. A sidecar replaces the directory record for that asset; otherwise the nearest `provenance.yaml` in the file's directory or one above it, up to the type root, answers. Each file resolves on its own, so a directory may hold files its `provenance.yaml` covers beside files a sidecar answers for. A file no record covers is an error at the file. Keep attribution with the authored asset so movement through the tree does not lose its source or license. See the [asset record reference](../reference/format-details.md#the-asset-record) for the accepted keys, inheritance, and examples.
+
+Every record states `attribution`, `license` and `ai` — whether a machine made the file, as the YAML boolean `true` or `false`. A record that leaves `ai` out is an error at the record; it is never read as `false`.
+
+```yaml
+attribution: Tom Rodriguez
+license: CC-BY-SA-4.0
+ai: false
+```
 
 A directory of portraits also states what the pictures in it are for:
 
 ```yaml
 attribution: Tom Rodriguez
 license: CC-BY-SA-4.0
+ai: false
 role: portrait
 ```
 
+## What the Foundry package ships
+
+The repository keeps every picture; the Foundry package carries a filtered copy, laid out flat. A picture ships when its record says `ai: false` and its licence is one of `LicenseRef-PublicDomain`, `CC0-1.0`, `CC0`, `CC-BY-3.0`, `CC-BY-4.0`, `CC-BY-SA-4.0` or `LicenseRef-NounProject-Pro`, together with any licence the package adds under `packageBuild.shippingLicenses`. A shipped picture sits at `icons/<basename>` or `images/<basename>` at the package root, whatever directories it is kept in here, and the package's asset set, `asset-sets/default.json`, lists what it ships.
+
+A note may still name a picture the package does not ship. Its compiled document draws the package's stand-in instead — `icons/missing.<ext>` or `images/missing.<ext>`, which you provide as an ordinary human-made picture licensed to ship, addressed `<package>-none-icon-missing` and `<package>-none-image-missing` — and keeps the real picture's address, so a world that holds the real file can point back at it. A package that leaves out a picture a note names, and ships no stand-in of that type, fails the build at the note. See [what a package ships](../reference/format-details.md#what-a-package-ships).
+
 **A hero image is 1792×768.** `data.banner` fills one fixed strip wherever it is drawn, so every banner is cut to that size and a picture of any other size is a finding naming both sizes — resize the picture to match. That is the one size any art field requires.
 
 `data.banner` reads in one of three states:

package/docs/commands.md

@@ -58,7 +58,7 @@ The command entries below list only their own options.
 the walk up from the working directory the CLI otherwise does — the only
 environment variable the toolchain itself reads for configuration
 resolution. `deploy`, `container` and `e2e` additionally read `FOUNDRYVTT_*`,
-documented where each applies.
+and `cdn publish` reads `CDN_*`, documented where each applies.
 
 An option name recurring across commands is not a recurring meaning —
 `--out`, `--check`, `--from` and `--strict` each carry their own default and
@@ -300,6 +300,16 @@ names a module in `packageBuild.assetTransform`, exporting
 anything else replaces its content. Reads every `from` path; writes into
 `packageBuild.stageDir`.
 
+Then stages the package's pictures itself. Every file under `assets/icons/`
+and `assets/images/` whose provenance says `ai: false` and whose licence is on
+the shipping list (the default list plus `packageBuild.shippingLicenses`) is copied flat to `icons/<basename>` or `images/<basename>`
+at the package root, through the same transform, and the package's asset set,
+`asset-sets/default.json`, lists what was staged. Everything else stays in the repository. See
+[what a package ships](reference/format-details.md#what-a-package-ships).
+A `packageBuild.assets` row that copies a picture root, a directory inside
+one, or a directory holding one is refused, because it would ship every file
+unfiltered.
+
 **OPTIONS**
 
 None.
@@ -307,15 +317,20 @@ None.
 **EXIT STATUS**
 
 1 if `packageBuild.assetTransform` is declared but cannot be loaded, or
-exports no `transform` function. 1 on any other thrown error. Otherwise 0 —
-including when `packageBuild.assets` is empty, which logs and stages nothing
-rather than failing.
+exports no `transform` function. 1 when a row copies a picture root, and 1 on
+any asset finding — a file no provenance record covers, a record missing
+`attribution`, `license` or `ai`, two files claiming one address — with
+nothing staged. 1 on any other thrown error. Otherwise 0.
 
 **EXAMPLES**
 
 ```
 $ package-build assets
-✅ Static assets staged (1 entries, 1 files).
+Pictures: 4 staged, 2 left out by provenance.
+✅ Static assets staged (2 entries, 9 files).
+
+$ package-build assets
+package-build.config.yaml:14:17: error: `packageBuild.assets[6]` copies `assets/images`, which reaches assets/images/ — the stage copies the icon and image roots itself, flat and filtered by each file's provenance, so a row copying them would ship every file unfiltered. Remove the row
 ```
 
 **SEE ALSO**
@@ -774,50 +789,6 @@ package-build: 1 template(s) fully localized and compiling.
 `package-build lang check`, `package-build lang coverage`,
 [Diagnostics](diagnostics.md), [Configuration](configuration.md).
 
-### `package-build labels check`
-
-**NAME**
-
-Compare the machine label registry against the documented reference table
-(`check` is the only action).
-
-**SYNOPSIS**
-
-```
-package-build labels check [--registry <path>] [--doc <path>]
-```
-
-**DESCRIPTION**
-
-Compares the machine label registry synced to GitHub against the documented
-reference table, and reports where they disagree — a label the registry has
-that the table does not, or the reverse. Neither derives from the other, so
-nothing else notices when they drift. Reads both files named below; writes
-nothing.
-
-**OPTIONS**
-
-| Option       | Type   | Default                      | Description                                                    |
-| ------------ | ------ | ---------------------------- | -------------------------------------------------------------- |
-| `--registry` | string | `.github/labels.yml`         | The machine registry synced to GitHub.                         |
-| `--doc`      | string | `.github/ISSUE_REPORTING.md` | The documented reference whose §3 table lists the same labels. |
-
-**EXIT STATUS**
-
-1 if either file does not exist. 1 if the registry and the table disagree on
-any label. Otherwise 0.
-
-**EXAMPLES**
-
-```
-$ package-build labels check --registry .github/labels.yml --doc .github/ISSUE_REPORTING.md
-package-build: registry and §3 agree (11 labels).
-```
-
-**SEE ALSO**
-
-None.
-
 ### `package-build bump [packages..]`
 
 **NAME**
@@ -1138,7 +1109,9 @@ states it a second time. It also publishes the content index the manifest
 advertises (`flags.metadataUrl`) and, when the stage carries one,
 `schema.json` — a repository that names `build/schema.json` in
 `packageBuild.assets` gets it released beside the archive; one that does not
-gets none. When the content tree holds notes beyond its homepage, it
+gets none. When the stage carries `asset-sets/default.json`, it writes
+`icons.zip` and `images.zip` too, one per picture root the stage holds, each
+with that set. When the content tree holds notes beyond its homepage, it
 also builds the content-tree book (see `package-build pdf`) and reports it
 alongside the archive; `--no-pdf` skips that step for a release that has a
 tree but does not want the book this time. A book that fails to build is
@@ -1246,6 +1219,134 @@ Deployed stage 'test' successfully.
 `package-build container <stage> <action>`, `package-build e2e <action>`,
 [Configuration](configuration.md).
 
+### `package-build cdn publish`
+
+**NAME**
+
+Upload every picture the package has to the CDN, and publish the art the
+package leaves out as a named asset set.
+
+**SYNOPSIS**
+
+```
+package-build cdn publish --set <file> --name <display name> [--dry-run]
+```
+
+**DESCRIPTION**
+
+The one writer to `<site.assets>/<contentPackage>/`. It is run by hand, or by
+a manually dispatched workflow; no build or release runs it.
+
+Every icon and image under the package's picture roots is uploaded flat, as
+`icons/<basename>` or `images/<basename>` — shipped and left-out pictures
+alike, because the website draws every one of them from the same address the
+site build gives it. `packageBuild.assetTransform` runs on each file exactly
+as `package-build assets` runs it, so a picture on the CDN holds the bytes the
+staged package holds. SVG is served as `image/svg+xml`.
+
+The bucket is served at `site.assets`, so an object's key is its path below
+that address: `thalorna/images/thorn.webp` is
+`https://cdn.heroiclands.org/thalorna/images/thorn.webp`.
+
+`--set` names the set file, written at `<site.assets>/<contentPackage>/<file>`.
+It lists only the pictures the package leaves out — an address a set does not
+list resolves to the shipped copy — chosen by the same rule the stage applies,
+`packageBuild.shippingLicenses` included. Its shape is the shipped set's, with
+each `source` the file's absolute CDN address:
+
+```json
+{
+  "name": "Thalorna — illustrated",
+  "package": "thalorna",
+  "assets": [
+    {
+      "address": "thalorna-none-image-thorn",
+      "source": "https://cdn.heroiclands.org/thalorna/images/thorn.webp",
+      "target": "images/thorn.webp",
+      "size": 48213
+    }
+  ]
+}
+```
+
+Several sets may sit side by side under one package, each with its own file
+name. `default.json` is refused: it is the shipped set's name.
+
+A picture whose object already exists at the same size is skipped, and the set
+file is skipped when its bytes are unchanged, so a second run uploads nothing.
+A picture that fails to upload is reported and the rest carry on; the set file
+is then withheld, since it would list a file the CDN does not hold.
+
+**Refusals and reports.** A file under `icons/` or `images/` whose name is no
+address — a basename that is not a shortcode, or two files claiming one — and
+a provenance record that cannot be read stop the run before anything is
+uploaded, each reported against its file. A note naming a picture the package
+does not have, and a note naming left-out art that is not on the CDN when the
+run ends, are warnings at the note's line and column: an art slot under
+`data:`, an embed, or a body image.
+
+**Credentials.** The store is an S3-compatible bucket — Cloudflare R2 for
+`cdn.heroiclands.org` — signed with AWS Signature Version 4. Its settings are
+read from the environment, after `.env.local` and `.env` are loaded:
+
+| Variable                | What it is                                                                |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `CDN_ENDPOINT`          | The S3 endpoint; for R2, `https://<account id>.r2.cloudflarestorage.com`. |
+| `CDN_BUCKET`            | The bucket served at `site.assets`.                                       |
+| `CDN_ACCESS_KEY_ID`     | The access key id of a token that can write the bucket.                   |
+| `CDN_SECRET_ACCESS_KEY` | That token's secret. Never printed.                                       |
+
+Setting some but not all of them is an error naming the missing ones. With
+none set, `--dry-run` compares against the public CDN at `site.assets`
+instead, read-only, and an upload is refused.
+
+A workflow calls the command the same way, passing the four values as named
+secrets in the step's environment:
+
+```yaml
+- run: npx package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
+  env:
+    CDN_ENDPOINT: ${{ secrets.CDN_ENDPOINT }}
+    CDN_BUCKET: ${{ secrets.CDN_BUCKET }}
+    CDN_ACCESS_KEY_ID: ${{ secrets.CDN_ACCESS_KEY_ID }}
+    CDN_SECRET_ACCESS_KEY: ${{ secrets.CDN_SECRET_ACCESS_KEY }}
+```
+
+**OPTIONS**
+
+| Option      | Type    | Default | Description                                                                 |
+| ----------- | ------- | ------- | --------------------------------------------------------------------------- |
+| `--set`     | string  | —       | Required. The set file's name under the package's CDN root, a `.json` file. |
+| `--name`    | string  | —       | Required. The set's display name.                                           |
+| `--dry-run` | boolean | `false` | List what would upload and what is skipped; write nothing.                  |
+
+**EXIT STATUS**
+
+1 when a picture's file has no address, when a picture fails to upload, when
+`--set` is `default.json` or a path, when `site.assets` is undeclared, and
+when an upload has no store configured. Warnings about notes do not change
+it. Otherwise 0.
+
+**EXAMPLES**
+
+```
+$ package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
+Dry run: comparing 582 pictures against https://cdn.heroiclands.org, read-only.
+  would upload thalorna/icons/anvilbdg.svg (969 bytes)
+  …
+  would upload thalorna/alt-art.json (582 assets)
+Would upload 582, skipped 0, failed 0; https://cdn.heroiclands.org/thalorna/alt-art.json lists 582 left-out pictures (would change).
+
+$ package-build cdn publish --set default.json --name Shipped
+package-build: `--set default.json` is refused: `default.json` is the shipped set's name, the fallback every other set is read against. Name the set for its art
+```
+
+**SEE ALSO**
+
+`package-build assets`, `package-build release`,
+[Configuration](configuration.md#site),
+[Release and deploy](guides/release-and-deploy.md#publish-pictures-to-the-cdn).
+
 ### `package-build container <stage> <action>`
 
 **NAME**
@@ -1306,7 +1407,9 @@ exact pin takes the major tag of its pin or of `compatibility.minimum`
 mount), `FOUNDRYVTT_CONTAINER_USER` (passed to `docker run --user`; `0:0`
 under rootless Docker makes the data root's files belong to the host user,
 because the image otherwise runs Foundry as user 1000 and ignores
-`FOUNDRY_UID` and `FOUNDRY_GID`).
+`FOUNDRY_UID` and `FOUNDRY_GID`), `FOUNDRYVTT_CONTAINER_S3` (`1` or `true`
+runs an S3-compatible server beside the container; see
+[an S3 server for the container](guides/e2e.md#an-s3-server-for-the-container)).
 
 **EXIT STATUS**
 

package/docs/configuration.md

@@ -206,6 +206,9 @@ against — the one reader of it is `resolveImg`
 `packageKind` and `foundryPackage`.
 
 - For a `systems` or `modules` package, `<packageKind>/<foundryPackage>/assets`.
+  A picture under `icons/` or `images/` is served flat from
+  `<packageKind>/<foundryPackage>/<icons|images>/<basename>` instead, the
+  layout the stage gives it; every other file keeps its path under `assets/`.
 - For a `documentation` package, `null` — Foundry serves no files for a
   package of this kind, and `documentation/null/assets` would be an address
   that resolves nowhere. `resolveImg` refuses rather than rooting a path
@@ -901,6 +904,12 @@ resolves every relative asset against it:
 
 > ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
 
+`package-build cdn publish` uploads the package's pictures under the same
+host, at `<site.assets>/<contentPackage>/icons/<basename>` and
+`…/images/<basename>`, which is the address the website gives each one. The
+bucket behind the CDN is served at `site.assets`, so an object's key is its
+path below this value.
+
 The generated Hugo configuration carries the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
 The two are one value read by two readers: the toolchain emits it into a
@@ -1685,7 +1694,7 @@ validator.
 packageBuild:
   assets:
     - { from: lang, to: lang }
-    - { from: assets/icons, to: assets/icons }
+    - { from: assets/audio, to: assets/audio }
   assetTransform: ./utils/svg-theme.mjs
   stageDir: build/stage
   clean:
@@ -1701,6 +1710,7 @@ packageBuild:
 | [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                                              |
 | [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                                       |
 | [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.shippingLicenses`](#packagebuildshippinglicenses)                           | array of strings                            | no       | `[]`                                                       |
 | [`packageBuild.baseStyles`](#packagebuildbasestyles)                                       | boolean                                     | no       | `true`                                                     |
 | [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
 | [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
@@ -1715,7 +1725,7 @@ packageBuild:
 | [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
 | [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
 
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, shippingLicenses, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
@@ -1765,6 +1775,15 @@ table says `lang`, not `build/stage/lang`.
 `assets` is the table of staging copies: source path in the repository,
 destination under the staged package root.
 
+**The picture roots are not in it.** `package-build assets` stages
+`assets/icons/` and `assets/images/` itself — flat at the package root, and
+only the files whose provenance allows them to ship (see
+[what a package ships](reference/format-details.md#what-a-package-ships)). A
+row whose `from` is a picture root, a directory inside one, or a directory
+holding one is refused at the row:
+
+> ``package-build.config.yaml:<line>:<column>: error: `packageBuild.assets[<index>]` copies `<from>`, which reaches assets/images/ — the stage copies the icon and image roots itself, flat and filtered by each file's provenance, so a row copying them would ship every file unfiltered. Remove the row``
+
 | Key                             | Type                       | Required |
 | ------------------------------- | -------------------------- | -------- |
 | `packageBuild.assets[].from`    | string                     | yes      |
@@ -1801,6 +1820,24 @@ repository has to compute. Neither declares anything, both default to
 
 > ``package-build config: `packageBuild.manifestFlags` must be a non-empty string.``
 
+### `packageBuild.shippingLicenses`
+
+Licences this package adds to the default shipping list. A picture ships in the
+Foundry package when its provenance says `ai: false` and its `license` is on the
+default list or on this one; the default list is never replaced, and `ai: true`
+never ships. Each entry is spelled exactly as provenance spells the licence.
+
+```yaml
+packageBuild:
+  shippingLicenses: [CC-BY-NC-SA-4.0]
+```
+
+> ``package-build config: `packageBuild.shippingLicenses` must be a list of licence identifiers.``
+
+> ``package-build config: `packageBuild.shippingLicenses` entry <index> must be a non-empty string.``
+
+> ``package-build config: `packageBuild.shippingLicenses` lists `<licence>` more than once.``
+
 ### `packageBuild.baseStyles`
 
 Whether the package takes the shared base stylesheet. It defaults to `true`,

package/docs/content-format.md

@@ -53,12 +53,36 @@ explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.
 
-An `affiliation` note declares `data.governance.ranks` with at least one rung at
-`level: 1`. Each rung states `level`, `title`, and `description`. A being's
-`data.affiliations` entry names a rank on that body's ladder; level 1 is the
-ordinary standing when no higher rank applies. A single level-1 rung is enough
-when the body expresses its hierarchy through `governance.offices` instead.
-Missing ranks, an empty list, or a ladder without level 1 are build errors.
+An `affiliation` note declares `data.governance.ranks` with at least two rungs:
+`level: 0`, those the body excludes, and `level: 1`, its ordinary members. Every
+body that can name its members can name those it shuts out, whether or not it
+ever does, so both are required. Each rung states `level`, `title`, and
+`description`, and the level-0 title is the body's own word for the excluded
+rather than a generic "Excluded". A being's `data.affiliations` entry names a
+rank on that body's ladder; level 1 is the ordinary standing when no higher
+rank applies.
+
+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 entry in
+`governance.offices` 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.
+```
+
+Missing ranks, an empty list, or a ladder without level 0 or level 1 are build
+errors, reported at the `ranks` key.
 
 | Authored section | SoHL Actor          | HM3 Actor            |
 | ---------------- | ------------------- | -------------------- |

package/docs/diagnostics.md

@@ -284,7 +284,7 @@ when it reports at least one `error`-severity diagnostic. A `warning` alone
 never fails a run.** `bin/report.mjs`'s `reportFindings` draws this line once
 for the commands built from the package's pure rule functions (`package-build
 lint`, `package-build lang check`, `package-build lang coverage`,
-`package-build yaml`, `package-build labels check`): it emits every finding
+`package-build yaml`): it emits every finding
 and returns only the count whose `severity` is `error`, and the command sets
 `process.exitCode = 1` exactly when that count is nonzero. Commands whose
 findings are hand-assembled — `package-build links`, `package-build
@@ -335,7 +335,6 @@ over one would teach people to stop reading the report.
 | `package-build lang check`                       | any localization finding is `error`-severity                                                                                                                                                                                                                       |
 | `package-build lang coverage`                    | a referenced key is missing (`error`-severity); an unreferenced key is always advisory and never fails the run                                                                                                                                                     |
 | `package-build yaml [paths..]`                   | any YAML finding is `error`-severity                                                                                                                                                                                                                               |
-| `package-build labels check`                     | the label registry and the documented table disagree on any label                                                                                                                                                                                                  |
 
 Every command also fails on a thrown error unrelated to a
 diagnostic — a missing configuration, an unreadable file, a network failure —

package/docs/guides/e2e.md

@@ -159,3 +159,41 @@ major version or moving tag is refused, because the result must name the
 build actually tested. A passing sweep provides evidence for choosing a
 new `compatibility.verified` value; a routine run exercises the pinned
 minimum build.
+
+## An S3 server for the container
+
+A suite that exercises S3 storage needs an S3-compatible server the browser and
+Foundry both reach. Setting `FOUNDRYVTT_CONTAINER_S3=1` when a container is
+created (`start`, `recreate`; through `e2e:fast --recreate` as well) provides one.
+Without it nothing changes: no network, no server, no extra environment.
+
+With it, before Foundry starts:
+
+- A user-defined network named `<container>-net` is created, and the Foundry
+  container is created on it.
+- A SeaweedFS server (`chrislusf/seaweedfs:3.80`) named `<container>-s3` joins
+  the network under the alias `s3.localhost` and publishes port 8333. Chromium
+  resolves every `*.localhost` name to loopback, so `http://s3.localhost:8333`
+  reaches the server from the browser and, through the alias, from the
+  container. Its CORS allows every origin.
+- The bucket `sohl-e2e` is created. Anonymous read and the test credentials come
+  from the identities file the server is started with.
+- The repository's `cypress/s3/aws-e2e.json` is copied into the data root's
+  `Config/`, and the container is created with `FOUNDRY_AWS_CONFIG=aws-e2e.json`.
+
+The repository supplies both files: `cypress/s3/s3-identities.json` (the
+SeaweedFS identities, including an `anonymous` identity with `Read`) and
+`cypress/s3/aws-e2e.json` (Foundry's `awsConfig`, pointing at
+`http://s3.localhost:8333`). The credentials are test-only. A missing file stops
+the start and names it.
+
+```bash
+FOUNDRYVTT_CONTAINER_S3=1 npm run e2e:fast -- --recreate
+```
+
+The container's environment is fixed when it is created, so an existing
+container started with the variable set joins the network but keeps the
+environment it was created with; `--recreate` applies `FOUNDRY_AWS_CONFIG`.
+`package-build container <stage> rm` with the variable set removes the server
+and the network along with the container. The server is otherwise left running
+between runs, bucket intact.

package/docs/guides/icons.md

@@ -68,6 +68,11 @@ defaults point into the system's `assets/images/` and `assets/icons/` trees,
 introduced by [HM3's asset-path migration](https://git.pupluppy.org/HeroicLands/HarnMaster-3-FoundryVTT/pulls/60).
 Use these defaults with an HM3 release that includes those assets.
 
+A compiled document reaches each icon in the deployed layout — the type root
+and the basename, `systems/sohl/icons/person.svg` — whatever directories hold
+it in the repository, and states its address in `flags.<system>.assets`. See
+[what a package ships](../reference/format-details.md#what-a-package-ships).
+
 ## Write an inline icon in prose
 
 Declare the glyph vocabulary in `package-build.config.yaml` or a separate YAML

package/docs/guides/module-project.md

@@ -861,7 +861,7 @@ everything that reads the tree runs before everything that writes the stage.
 
 [`project-setup.md`](../project-setup.md) turns this into npm scripts, and covers
 everything a repository carries beyond the build itself: the git hooks, the
-changeset directory, the label registry, and what each script in the chain is
+changeset directory, and what each script in the chain is
 for.
 
 ## What comes next

package/docs/guides/release-and-deploy.md

@@ -47,7 +47,10 @@ manifest under `build/dist/`. The ZIP contains the staged tree at its root,
 which is the shape Foundry installs. When the manifest advertises a content
 index, the corresponding metadata JSONL is also placed beside the ZIP. A
 manifest that advertises an index the build has not produced fails the
-release. An opted-in staged `schema.json` is published beside it too.
+release. An opted-in staged `schema.json` is published beside it too. A
+package whose stage holds pictures also gets `icons.zip` and `images.zip`:
+each holds one picture root of the stage, flat, with the package's asset
+set `asset-sets/default.json`, so a GM can place the files by hand.
 
 When the package publishes content and has a book configuration, the release
 also builds a PDF beside the archive. Book findings are reported without
@@ -128,6 +131,38 @@ the same stage;
 [container command](../commands.md#package-build-container-stage-action) for
 the other actions and environment variables.
 
+## Publish pictures to the CDN
+
+The website draws every picture a package has from
+`<site.assets>/<contentPackage>/`, and the art a Foundry package leaves out
+reaches a world from there as a named asset set. `package-build cdn publish`
+is the one command that writes there:
+
+```bash
+package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
+package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
+```
+
+It uploads every icon and image flat, transformed as the stage transforms
+them, skips what the CDN already holds at the same size, and writes
+`<site.assets>/<contentPackage>/alt-art.json` listing the left-out pictures.
+Run it after the pictures or their provenance change; it is not part of a
+build or a release.
+
+The bucket's credentials go in `.env.local` beside the stage paths:
+
+```dotenv
+CDN_ENDPOINT=https://<account id>.r2.cloudflarestorage.com
+CDN_BUCKET=<bucket>
+CDN_ACCESS_KEY_ID=<access key id>
+CDN_SECRET_ACCESS_KEY=<secret access key>
+```
+
+A dry run with none of them set compares against the public CDN instead. A
+dispatched workflow passes the same four values as named secrets. See the
+[command reference](../commands.md#package-build-cdn-publish) for the set
+file's shape, the refusals and the exit status.
+
 ## Publish a package-build npm version
 
 For this toolchain's own npm release, a pull request with a change installers