@heroiclands/package-build 23.0.0 → 23.1.1

package/docs/authoring/links-and-markup.md

@@ -37,7 +37,7 @@ The harbor faces west.
 Travelers present their papers here. See [[#harbor|the harbor]].
 ```
 
-A leading caption starts a captioned-item JournalEntryPage in Foundry. A solitary image with a plain caption can be an image page; other captioned items become text pages. Websites and books keep captioned items in the surrounding flow.
+A leading caption gives its item a JournalEntryPage of its own in Foundry, and the body after the item resumes on a continuation of the surrounding section. A solitary image with a plain caption can be an image page; other captioned items become text pages. Websites and books keep captioned items in the surrounding flow.
 
 The prose introducing a fence and the fence itself land on two different Foundry pages, so a reference such as `{{ref "#trade"}}` written just above a fence sends a Foundry reader to a different page than the one carrying the sentence. Give the introducing prose its own heading, or accept that following the reference leaves the page, before relying on a fence to sit inside a longer page's flow.
 
@@ -59,7 +59,7 @@ The section runs from that heading to the next heading that opens a page. In Fou
 
 **On the website this is a spoiler, not access control.** The withheld section is in the published page, so anyone who opens the element or reads the page source reads it. Foundry is the only surface that withholds anything. Write nothing in a `.secret` section that would matter if a player read it on the web.
 
-A `:::secret` block inside the section is legal and renders as it does anywhere else. `.secret` on a heading that opens no page — a lower-level heading with no anchor — covers no page, and is reported at its own line: give that heading an anchor, or raise it to the top level.
+A captioned item inside the section is withheld with it: in Foundry the item's own page, and the page that resumes the section after it, are the GM's alone. A `:::secret` block inside the section is legal and renders as it does anywhere else. `.secret` on a heading that opens no page — a lower-level heading with no anchor — covers no page, and is reported at its own line: give that heading an anchor, or raise it to the top level.
 
 The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields, and take an H1 only — not the lower-level heading a journal page may otherwise start from. The section runs to the next H1, nested headings included. An anchor declared on a lower heading is still found, and is a build error rather than a quietly empty field: move the heading to the top level, or drop the anchor if the section is meant to stay unaddressed prose.
 
@@ -98,9 +98,9 @@ Each numbered type has its own counter. Websites and Foundry number within a not
 
 `{{ref "#trade"}}` displays the numbered label as a link. `form="full"` includes caption text and `form="title"` displays the caption alone. Use title form for an unnumbered caption. Cross-note references can name the note address before the anchor, such as `{{ref "place-harbor#trade"}}`; the displayed number belongs to the target on the surface rendering it. Links inside caption text contribute their visible text to references, so the reference does not contain a nested link.
 
-Foundry gives a captioned item its own JournalEntryPage. A solitary image with a plain caption can use an image page; captions with inline markup and other items use text pages. On the website and in the book the item stays in the flow of the surrounding page.
+Foundry gives a captioned item a JournalEntryPage holding the item alone, named for its number or, unnumbered, for the caption's visible text — links and emphasis reduced to the words a reader sees. A solitary image with a plain caption can use an image page; captions with inline markup and other items use text pages. The body after the item resumes on a continuation page carrying the interrupted section's name, level and classes, with its title hidden; nothing is emitted when the next page begins straight after the item. On the website and in the book the item stays in the flow of the surrounding page.
 
-**Migration:** `:::figure` is no longer supported. Move the former `///` caption before the item as `:@ Caption {#id}` and remove the figure wrapper. To caption a group or passage, put it inside a generic fenced div and caption that div with an explicit type if needed. `///` is no longer a caption delimiter.
+To caption a group or passage, put it inside a generic fenced div and caption that div, with an explicit type where the inferred one does not fit.
 
 ## Images and protected content
 
@@ -168,8 +168,6 @@ Attributes follow the marker and apply to the alert:
 
 Use `#id`, `.class` and named attributes in the shared braced grammar. The marker determines the default label, icon and color. An authored `title` replaces the default **Note**, **Tip**, **Important** or **Warning** heading while preserving the alert type’s icon and color. Event-handler attributes, malformed attributes, unknown alert types and empty alert bodies are errors. Ordinary blockquotes and alert examples inside literal code remain unchanged. A leading caption can describe an alert as a quote block, normally with the `prose` type or an explicit `example` type.
 
-Migrate former info blocks to `[!NOTE]` alerts and warn blocks to `[!WARNING]` alerts. The old named fences are errors. `:::secret` remains supported.
-
 ### Secret blocks
 
 `:::secret` sets GM material apart. Its optional attributes accept an identifier, classes and named attributes. `title` supplies its heading; without a title the heading is **Secret**:
@@ -244,7 +242,7 @@ The lantern marks the shore.
 ```
 ````
 
-This uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. Use `:` for a caption without a number. `:::poetry` is no longer supported.
+This uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. Use `:` for a caption without a number.
 
 ## Footnotes and definition lists
 
@@ -311,14 +309,108 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 
 ### What a query can read
 
-| Relation          | What it holds                                                                                                                 |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `notes`           | Every note except a stub. This is the one to use unless a stub is wanted.                                                     |
-| `entries`         | Every note, stubs included.                                                                                                   |
-| `market`          | The market scale as three columns — `value`, `name`, `trade` — so a table can print `village` beside the number a note wrote. |
-| `<package>.notes` | The same two relations for each package this one declares a dependency on, in a schema named for it.                          |
+| Relation          | What it holds                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `notes`           | Every note except a stub. This is the one to use unless a stub is wanted.                                                            |
+| `entries`         | Every note, stubs included.                                                                                                          |
+| `events`          | One row per event a `lore`, `place` or `affiliation` note writes in `data.events`, with `whenSort` to order them by date.            |
+| `market`          | The market scale as three columns — `value`, `name`, `trade` — so a table can print `village` beside the number a note wrote.        |
+| `<package>.notes` | The same relations — `notes`, `entries` and `events` — for each package this one declares a dependency on, in a schema named for it. |
+
+Nested frontmatter is addressed exactly as a note writes it: `name.full`, `sohl.weight`, `data.born`. Every Address is a string — the full canonical Address, as in `list_contains(data.parents, 'thalorna-note-place-xerathia')` — whichever package published it. Every note carries a computed `state` column of `full`, `draft` or `stub`. Notes tagged `gm` are absent from the relations on public surfaces.
+
+### Sections the build adds
+
+The build adds sections to the end of a note, after everything you wrote, listing what other notes say about it. Each appears only where it has something to list, under a fixed anchor:
+
+| Section           | Anchor           | Lists                                                                |
+| ----------------- | ---------------- | -------------------------------------------------------------------- |
+| Within            | `within`         | on a place, the places whose `parents` name it, grouped by kind      |
+| Governed by       | `governedby`     | on a place, the affiliation its `government` names                   |
+| Governed places   | `governedplaces` | on an affiliation, the places naming it as their `government`        |
+| In song and story | `insongandstory` | the works of literature whose `subjects` name the note or its events |
+| From here         | `fromhere`       | on a place with borders or routes, the map drawn from it             |
+
+The event sections below sit among them, and the [format reference](../reference/format-details.md#generated-sections) gives the order. Each entry links to the note it names; a note with no page of its own is named in plain text. Replace a section the way you replace an event view, by writing your own with the same anchor:
+
+```markdown
+# Within {#within}
+
+The vale holds three villages, of which only [[place-ford|Ford]] is walled.
+```
+
+### Sections the build adds about events
+
+A note's events are listed for you on the notes they concern: a place gets a **Chronology** of what happened there and below it, with every `depth: world` event as context, a being, affiliation or people the **Events** it took part in, an affiliation, place or people the **Accounts** it gives, and a note holding events **What followed** them. Each is a section appended after everything you wrote, with a fixed anchor — `chronology`, `events`, `accounts`, `followed` — and it appears only where it has something to list.
+
+To replace one, write the section yourself with the same anchor. The build then adds nothing for it and leaves yours exactly as written:
+
+````markdown
+# Chronology {#chronology}
+
+The fells keep no reckoning before the raising.
+
+```sql
+SELECT summary AS "What happened", "when" AS "When"
+FROM events
+WHERE list_contains("where".locus, 'thalorna-note-place-ironfells')
+ORDER BY whenSort
+```
+````
+
+The [format reference](../reference/format-details.md#event-views) lists what each view selects.
+
+### A century view
+
+A view of what happened in one century is a fence an author writes, on whatever note should carry it. Filter `events` on `whenYear`, leave out events of local reach, and order by `whenSort`:
+
+````markdown
+# The Third Century {#third-century}
+
+```sql
+SELECT note                                   AS _ref,
+       summary                                AS "What happened",
+       "when"                                 AS "When",
+       array_to_string("where".locus, ', ')   AS "Where"
+FROM events
+WHERE whenYear BETWEEN 200 AND 299
+  AND depth <> 'local'
+ORDER BY whenSort, address
+```
+````
+
+Each row is one event, linked to the note that records it, with its date as the note wrote it and the Addresses of the places it happened at:
+
+| What happened                                      | When | Where                                              |
+| -------------------------------------------------- | ---- | -------------------------------------------------- |
+| [Ironfells is sacked.](/thalorna/place-ironfells/) | ~280 | thalorna-note-place-ironfells                      |
+| [The fords are bridged.](/thalorna/lore-fords/)    | ~291 | thalorna-note-place-east, thalorna-note-place-west |
+
+`depth <> 'local'` also leaves out an event that states no `depth`; write `depth IS DISTINCT FROM 'local'` to keep those. `whenYear` is the year on the canonical axis, which counts a year `0` that written dates skip: a year written after zero keeps its number, and one written before zero sits one higher. So `whenYear BETWEEN -299 AND -200` selects the events written `-300` to `-201`.
+
+To print each place by its name rather than its Address, join `notes` on the place's Address. The `GROUP BY` keeps one row per event when it happened in several places:
+
+````markdown
+```sql
+SELECT e.note                          AS _ref,
+       e.summary                       AS "What happened",
+       e."when"                        AS "When",
+       string_agg(p.name.full, ', ')   AS "Where"
+FROM events e
+LEFT JOIN notes p ON list_contains(e."where".locus, p.address.canonical)
+WHERE e.whenYear BETWEEN 200 AND 299
+  AND e.depth <> 'local'
+GROUP BY e.note, e.address, e.summary, e."when", e.whenSort
+ORDER BY e.whenSort, e.address
+```
+````
+
+| What happened                                      | When | Where      |
+| -------------------------------------------------- | ---- | ---------- |
+| [Ironfells is sacked.](/thalorna/place-ironfells/) | ~280 | Ironfells  |
+| [The fords are bridged.](/thalorna/lore-fords/)    | ~291 | East, West |
 
-Nested frontmatter is addressed exactly as a note writes it: `name.full`, `sohl.weight`, `data.born`. Every note carries a computed `state` column of `full`, `draft` or `stub`. Notes tagged `gm` are absent from the relations on public surfaces.
+An event with no `where.locus` keeps its row with an empty **Where** cell.
 
 ### Fence attributes
 
@@ -418,24 +510,48 @@ There are {{words (sql "SELECT COUNT(*) FROM notes WHERE type = 'being'")}} bein
 
 <!-- expression-helpers:start -->
 
-| Helper       | Parameters                                 | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eq`         | `a b`                                      | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `gt`         | `a b`                                      | True when a is greater than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `gte`        | `a b`                                      | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `lt`         | `a b`                                      | True when a is less than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `lte`        | `a b`                                      | True when a is less than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `not`        | `value`                                    | True when the value is false, zero, empty or absent.                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `and`        | `value …`                                  | True when every value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `or`         | `value …`                                  | True when any value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `words`      | `number`                                   | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                                                                                                                                                                                                                                                                                                                            |
-| `digits`     | `number`                                   | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                                                                                                                                                                                                                                                                                                                             |
-| `sql`        | `"query"`                                  | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                                                                                                                                                                                                                                                                                                                                       |
-| `dateformat` | `calendar date ["format"]`                 | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern.                                                                                                                                                                                                                                                                                                          |
-| `ref`        | `address [form="number"\|"full"\|"title"]` | A link to a captioned item, by its anchor — `"#thorn"` on this note, `"note-address#thorn"` on another. `form` is `number` (the default, and admitted explicitly), rendering "Figure 13"; `full`, the number and the caption; or `title`, the caption alone. Always renders as a link to the figure, and a link inside the caption contributes only its label text. The number rendered is the one the figure carries on the surface doing the rendering, whichever note names it. |
+| Helper       | Parameters                                                                                             | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `eq`         | `a b`                                                                                                  | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `gt`         | `a b`                                                                                                  | True when a is greater than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `gte`        | `a b`                                                                                                  | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `lt`         | `a b`                                                                                                  | True when a is less than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `lte`        | `a b`                                                                                                  | True when a is less than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `not`        | `value`                                                                                                | True when the value is false, zero, empty or absent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `and`        | `value …`                                                                                              | True when every value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `or`         | `value …`                                                                                              | True when any value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `words`      | `number`                                                                                               | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `digits`     | `number`                                                                                               | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `sql`        | `"query"`                                                                                              | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `dateformat` | `calendar date ["format"]`                                                                             | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `ref`        | `address [form="number"\|"full"\|"title"] \| address field="when"\|"until"\|"kind"\|"summary"\|"name"` | A link to a captioned item, by its anchor — `"#thorn"` on this note, `"note-address#thorn"` on another. `form` is `number` (the default, and admitted explicitly), rendering "Figure 13"; `full`, the number and the caption; or `title`, the caption alone. Always renders as a link to the figure, and a link inside the caption contributes only its label text. The number rendered is the one the figure carries on the surface doing the rendering, whichever note names it. With `field` in place of `form`, the address names an event — `"place-ironfells#sack"`, `"#sack"` on this note, or `"lore-founding"` for a note holding one event — and the reference prints that event's `when`, `until`, `kind`, `summary` or `name` as plain text, never a link; a date prints as the note format prints any date. |
 
 <!-- expression-helpers:end -->
 
 A helper that is given the wrong kind of value reports it rather than printing something wrong: `words` refuses a decimal, the four comparisons refuse anything that is not a finite number, and `dateformat` refuses a date it cannot resolve in the calendar it was given.
 
 See [date rules](dates-and-calendars.md) for what `dateformat` accepts and the patterns its third argument names.
+
+### An event's date, inline
+
+`ref` with `field` in place of `form` prints one field of an [event](../reference/format-details.md#events) as plain text, so a sentence states a date from the one place the event records it rather than typing it a second time:
+
+```markdown
+Ironfells fell in {{ref "place-ironfells#sack" field="when"}}, in what the fells call {{ref "place-ironfells#sack" field="name"}}.
+The chronicle records the founding in one line: {{ref "lore-founding" field="summary"}}
+Our own sack was a {{ref "#sack" field="kind"}}.
+```
+
+The address names one event: `"<note>#<id>"` for an event of another note, `"#<id>"` for one of this note, or a note's Address alone when that note holds exactly one event. An event a declared dependency publishes is named by its full Address, as any cross-package link is.
+
+| `field`   | What prints                                                        |
+| --------- | ------------------------------------------------------------------ |
+| `when`    | The event's date, as the note format prints any date — `~` is kept |
+| `until`   | The date it ended, printed the same way                            |
+| `kind`    | Its `kind`, such as `siege`                                        |
+| `summary` | Its `summary`; a link written inside it prints as its label        |
+| `name`    | The first name its `names` list gives                              |
+
+The value is text and never a link, on the website, in the Foundry journal and in the book alike. `field` is a quoted string, like `form`, and a reference takes one or the other.
+
+Each of these is an error at the reference's own line and column, and the reference's text stays in the page: an address naming no note, an anchor the note does not declare, an anchor that is a heading or another `prose` anchor rather than an event, a note holding several events or none named without an `#id`, a `field` outside the five above, and a field the event does not state — `field="until"` on an event with no `until`, or `field="name"` on one with no `names`.

package/docs/commands.md

@@ -2451,16 +2451,14 @@ not change its viewpoint.
 
 Site builds put a linked SVG in each eligible place page. PDF builds put a
 vector map on its own page immediately after each selected place entry with
-relations. A configured Scene pack stages PNG backgrounds and emits gridless
-itinerary Scenes and an Adventure containing the journals their pins open.
-The installed SVG renderer also stages PNG backgrounds for authored regional SVG maps.
-
-Battle and local map notes can carry a Foundry Scene export under `data.scene`.
-The pack compiler preserves its fields and binds pins marked `#anchor` to pages
-from the map note's Markdown. A `totm` map uses an image Address and canvas
-dimensions to make a gridless Scene.
-`data.fixup` resolves asset Addresses into selected fields of an exported Scene;
-a missing path or asset is a build error.
+relations. The drawings are pictures for a reader; no Foundry Scene is made
+from them.
+
+A map note is a different thing: it carries a Scene exported from Foundry under
+`data.scene`, on every map subtype. The pack compiler passes it through, binds
+pins marked `#anchor` to pages from the map note's Markdown, and applies
+`data.fixup`, which resolves asset Addresses into selected fields of the
+exported Scene; a missing path or asset is a build error.
 
 The four drawings, any of which may be asked for in one run:
 

package/docs/configuration.md

@@ -1002,15 +1002,16 @@ site:
 
 > ``package-build config: `site.search` must be a boolean.``
 
-`site.maps` is whether every place page carries the map from that place. On
-by default: `package-build site` draws the map `package-build map --from`
-draws — the place's borders and routes, each neighbour at its bearing — for
-every place that states a border or a route or is named in one, lays it beside
-the page as `from-<shortcode>.svg`, and names the file in the page's front
-matter as `map`, which the theme inlines so every place name on it is a link
-to that place's page. A place with no relation carries no map and no key.
-The Graphviz runtime installed with package-build draws the maps. `false`
-draws nothing.
+`site.maps` is whether a place carries the map from it. On by default: every
+place that states a border or a route, or is named in one, is given a
+**From here** [generated section](reference/format-details.md#generated-sections)
+holding the map `package-build map --from` draws — the place's borders and
+routes, each neighbour at its bearing. The section reaches every surface: the
+website sets the drawing inline so every place name on it is a link to that
+place's page, the Foundry compile stages it into the module, and the book
+prints it in the place's entry. A place with no relation carries no map. The
+Graphviz runtime installed with package-build draws the maps. `false` gives no
+place the section, on any surface, and draws nothing.
 
 ```yaml
 site:
@@ -1084,8 +1085,9 @@ determined by the authored content tree: a tree containing only a homepage has
 no content pages for a book.
 
 Each selected place with a border or route receives a dedicated full-page
-vector itinerary after its entry. A selected authored regional SVG map also
-prints on its own page. The npm-installed Graphviz runtime draws itineraries.
+vector itinerary after its entry. A selected map note prints each of its
+exported Scene's level backgrounds on its own page. The npm-installed Graphviz
+runtime draws itineraries.
 
 ```yaml
 pdf:

package/docs/content-format.md

@@ -29,7 +29,7 @@ A nonempty note body creates one system-agnostic Foundry JournalEntry. Content b
 
 Leading `:` captions describe the next supported block; `:@` captions also number it. The optional type accepts `figure`, `table`, `poetry`, `code`, `prose`, and `example`. Captions support identifiers, classes and named attributes; unsupported following blocks are errors. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references).
 
-A code fence with language `poetry` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. The former `:::figure` and `:::poetry` forms are removed. See [poetry](authoring/links-and-markup.md#poetry), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans).
+A code fence with language `poetry` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [poetry](authoring/links-and-markup.md#poetry), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans).
 
 Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with
@@ -88,6 +88,6 @@ The note's readable Address is `<package>-note-lore-harbor`. In prose, link to i
 
 The [first-note guide](authoring/first-note.md) shows the build commands and how to add a system document. Use the [command reference](commands.md) for exact flags and the [diagnostics guide](diagnostics.md) for located errors.
 
-Place notes may declare a governing affiliation with `data.government`, or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](authoring/frontmatter.md#place-governments) and [government migration](guides/government-migration.md).
+Place notes may declare a governing affiliation with `data.government`, or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](authoring/frontmatter.md#place-governments).
 
 Blockquote alerts use `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!]`, with optional attributes after the marker. They replace the former info and warn div fences; secret blocks remain supported. See [alerts](authoring/links-and-markup.md#alerts).

package/docs/guides/book.md

@@ -92,10 +92,9 @@ columns; a wide table outside a figure fence starts on a new page so it stays
 after its introduction. A wide table inside one may float to the page top, and
 its label stays with it. A table too tall for one page takes pages of its own.
 A figure's number runs through the whole book in reading order, counted within
-its own kind. Maps attached
-to selected places use landscape pages after those entries. Regional, theatre
-of the mind, battle, and local map backgrounds also print on landscape pages.
-Battle and local maps print each Scene level's background on its own page.
+its own kind. A place on a border or a route prints the map drawn from it in
+its **From here** section, inside its own entry and nowhere else. A map note prints
+each of its exported Scene's level backgrounds on its own landscape page.
 The
 [content format](../content-format.md) describes image sizes, floats, and
 links as they are authored in notes.
@@ -106,6 +105,49 @@ and map backgrounds fit the landscape map area. An image smaller than that
 target keeps its authored pixels and still fills its allotted space on the
 page. SVG art stays vector. The build never changes authored image files.
 
+## The index
+
+A book that prints at least one note ends with an **Index** chapter, grouped
+under letter headings. Nothing configures it: the build derives it from the
+notes the book prints.
+
+| Term                     | Source                | Shown as                                                                           |
+| ------------------------ | --------------------- | ---------------------------------------------------------------------------------- |
+| A note's name            | `name.full`           | the page of the note's entry in **bold**, then the pages of every authored mention |
+| An alias                 | `name.aliases`        | _see_ the note's name                                                              |
+| An event's in-world name | `data.events[].names` | _see_ the name of the note that holds the event                                    |
+
+To get a term into the index, give the note a `name.full`, add an alias or an
+event name, or link to the note from prose with a wikilink. A wikilink to a note
+the book prints adds the page it appears on. A term mentioned several times on
+one page lists that page once, and a note printed under more than one section
+is listed once, with every page it occupies.
+
+Two kinds of link add nothing:
+
+- **Links in generated sections** such as "Within" or "Governed by". They name
+  notes the build chose rather than the author, and would add a page to nearly
+  every place and bury the authored mentions. They print the page of the note's
+  entry beside the name instead, as
+  described under [Build and inspect](#build-and-inspect).
+- **Links to a note the book does not print.** There is no page to point to.
+
+Terms sort on the ASCII fold the content index derives for names (`nameAscii`),
+ignoring case, so an accented name files under its base letter and the order
+matches the table of contents. A term that does not begin with a letter files
+first, under `#`. An alias or event name that folds to the same text as the
+note's own name is not listed again.
+
+Two notes that print the same name are told apart. Each is qualified with the
+note's subtype, or its type where it has none, as in `Ashkabel (settlement)` and
+`Ashkabel (character)`. Where that still collides, the name of the place the
+note is within is added: `Ashkabel (settlement, Harn)`. An alias or event name
+that points at a qualified name prints the qualifier too.
+
+Page numbers come from the typeset book, so they stay correct however the pages
+reflow, and each is a link to its page in the PDF. The Index is reached from the
+Contents and the bookmarks like any other chapter.
+
 ## Set fonts and icon fonts
 
 The build supplies its default book fonts and searches its own font directory
@@ -152,3 +194,16 @@ a note outside the selection or another package remains a web address.
 Anchors on headings are scoped to their entries, so two entries can use the
 same heading anchor. The build reports an unresolved destination while
 keeping the source available for inspection.
+
+The [generated sections](../reference/format-details.md#generated-sections)
+an entry carries — **Within**, **Governed by**, **In song and story**, the
+event views and the rest — name notes the build chose rather than the author,
+so their links follow their own rule, because a book is often a selection:
+
+- A name whose note is in the book is an internal link followed by the page
+  that note's entry starts on, printed as the contents prints it:
+  `Ford (p. 12)`. The number is Typst's own, read after layout.
+- A name whose note is not in the book is printed as plain text, with no link,
+  no page and no finding.
+
+Links an author wrote keep the rules above and carry no page number.

package/docs/guides/icons.md

@@ -39,15 +39,14 @@ data:
 Here `data.icon` resolves an `icon` asset and `data.tokenIcon` resolves an
 `image` asset. A full address, such as `sohl-none-image-smith-token`, names
 another package when that package is available to the build. `data.icon` and
-`data.tokenIcon` default to the `icon` type; `data.bgImage` and `data.banner`
-default to `image`. An explicit `image-` or `icon-` type works in any of the
-four slots. A pathname with slashes or an extension is not an art-slot address.
+`data.tokenIcon` default to the `icon` type; `data.banner` defaults to
+`image`. An explicit `image-` or `icon-` type works in any of the three
+slots. A pathname with slashes or an extension is not an art-slot address.
 
 | Art slot         | Its use                                         |
 | ---------------- | ----------------------------------------------- |
 | `data.icon`      | Profile art on a compiled Actor or Item         |
 | `data.tokenIcon` | Actor token art; follows `data.icon` when unset |
-| `data.bgImage`   | Background of a map Scene                       |
 | `data.banner`    | Page hero image for the site                    |
 
 An Item without `data.icon` uses its builder's configured default art. An
@@ -55,7 +54,7 @@ Actor without `data.icon` uses its compiled default art. Write `data.icon`
 when the note needs a particular image. A portrait within the prose is an
 image embed, for example `![[image-smith-portrait|The smith]]{size=medium}`;
 it does not set a document's profile art. The
-[art-slot reference](../reference/format-details.md#the-four-art-slots) gives each
+[art-slot reference](../reference/format-details.md#the-art-slots) gives each
 slot's type and document destination.
 
 A being's `subType` selects its compiled default art: `character` and `npc`

package/docs/guides/packs.md

@@ -165,3 +165,9 @@ the needed output must already exist. The full compile orders those passes for
 you. `package-build package unpack` reads a built pack back into JSON for
 inspection. See the [command reference](../commands.md) for their arguments
 and output paths.
+
+A compile also draws the map from each place given a **From here**
+[generated section](../reference/format-details.md#generated-sections) and
+stages it into the module at `assets/generated/from-<shortcode>.svg`, beside
+the compiled packs, where the section's image resolves. Each generated section
+starts its own page of the note's journal, as any H1 does.

package/docs/guides/reference-pages.md

@@ -136,7 +136,27 @@ The index is disposable build output; regenerate it from the authored tree
 when the content changes.
 
 The record's `address.canonical` is the full Address. Its `address.slug` is a
-local web link target. A stub has `address: null` and `anchors: null`; its
+local web link target. Each entry of `anchors` carries its `slug`, `name`, `line`,
+`link` and `kind` — `prose` for an anchor the body declares, `event` for an
+event's `id` — so a note's events are listed there beside its body anchors. A
+dependency's events are resolved through this list and through each event's
+resolved date under `resolvedDates.events`.
+
+**Every Address in the file is an object**, wherever it appears — `address.canonical`,
+`documentation`, an anchor's `link`, and every Address a note writes:
+
+```json
+{ "address": "thalorna-note-place-xerathia", "anchor": null, "anchorKind": null }
+{ "address": "thalorna-note-lore-crown", "anchor": "founding", "anchorKind": "event" }
+```
+
+`address` is the full canonical Address, `anchor` the anchor's slug or `null`,
+and `anchorKind` its kind, `prose` or `event`, or `null`. A map keyed by
+Address, such as a being's `affiliations`, keeps string keys: JSON keys are
+strings, and no Address-keyed field takes an anchor. A package and every
+package it depends on build with the same index format, since each reads the
+others' published files. The SQL tables present each Address as a plain
+string. A stub has `address: null` and `anchors: null`; its
 frontmatter remains queryable. An Item or Actor note can have both a readable
 `note` record and a game-system document destination. A generated
 `documentation` pointer connects a system document to its readable note.

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

@@ -31,7 +31,7 @@ document ID appears under another address, and **withdrawn** when that ID
 appears under none. Findings are warnings by default. `--strict` turns them
 into errors for a release gate. The comparison reads shipped Item packs, so it
 reports the surface consumers actually resolve rather than inferring changes
-from filenames. Use the [Address reference](../reference/format-details.md#addresses)
+from filenames. Use the [Address reference](../content-format.md#addresses)
 when choosing a durable shortcode.
 
 ## Build the release files
@@ -105,10 +105,42 @@ change is minor; an optional command, flag, or key is patch. A major bump
 requires the maintainer's direct decision. `package-build changelog check`
 checks the quality of any pending changeset.
 
-Merging a changeset to `main` makes the **Version Packages** pull request. Its
-generated changelog section is reviewed as the release note. Merging that
-pull request runs the **Publish to npm** workflow: npm Trusted Publishing
-publishes the version, and the workflow creates its version tag and GitHub
-Release. The workflow's manual dispatch can retry publishing a version already
-merged to `main`. The [npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
+The repository's primary forge is Gitea, and GitHub is its push mirror. The
+release runs in two halves, one on each:
+
+1. **Version, on Gitea.** Merging a changeset to `main` runs
+   `.gitea/workflows/release.yml`, which opens or updates the **Version
+   Packages** pull request. Its generated changelog section is reviewed as the
+   release note. Merging that pull request runs the same workflow again, which
+   pushes the tag `v<version>` at the merged version commit. Releasing from
+   Gitea is switched on by the repository variable `HL_RELEASE_ENABLED`.
+2. **Publish, on GitHub.** The push mirror carries the tag to GitHub, where it
+   starts the **Publish to npm** workflow, `.github/workflows/release.yml`. It
+   refuses a tag that names a commit outside `main` or that is not
+   `v<version>` of the tagged `package.json`. When npm does not have the
+   version yet, it runs the tests and publishes through npm Trusted Publishing
+   with provenance. It then creates the GitHub Release from the version's
+   changelog section, unless one exists.
+
+Nothing on Gitea publishes to npm, and nothing on GitHub runs for a branch
+push. Every step of the GitHub half is safe to repeat: re-running it, or
+dispatching it with the tag as its ref, finishes a release whose publish or
+Release step failed and changes nothing for one that completed. The
+[npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
 shows the published version and README.
+
+Two scripts in this repository's own `package.json` run the same steps at a
+desk:
+
+- **`npm run build`** runs `package-build ci`: the Build & Test workflow's
+  `run:` steps in a `linux/amd64` container over a clean export of `HEAD`.
+  `npm run build -- --native` runs them on the host in the working tree instead.
+  Off Linux, the Typst, GraphViz and Hugo steps install nothing; each uses the
+  tool already on `PATH` and stops with `<tool> is not on PATH` when it is
+  missing, so a Mac running `--native` needs `typst`, `dot` and Hugo extended
+  installed first.
+- **`npm run deploy:npm`** runs `npm publish`. Provenance is attested only on a
+  CI runner that can mint a Sigstore identity — GitHub Actions with an OIDC
+  token, or GitLab CI with `SIGSTORE_ID_TOKEN` — and anywhere else the publish
+  goes ahead without it. Arguments after `--` reach `npm publish`, so
+  `npm run deploy:npm -- --dry-run` lists the tarball without publishing.