@heroiclands/package-build 22.26.0 → 22.28.0

package/docs/reference/format-details.md

@@ -567,9 +567,9 @@ an author writes — and each type that has any names them under its table.
 
 **An `Address` becomes a `Shortcode` where the target field expects one.** SoHL
 resolves a stored cross-reference among the items one actor holds, and packages do
-not exist there, so the field holds a `Shortcode`. Four `affiliation` fields are
+not exist there, so the field holds a `Shortcode`. Three `affiliation` fields are
 authored as Addresses and stored that way: `data.seat` becomes `system.seat`,
-`data.parents` becomes `system.parents`, `data.domains` becomes `system.domain`,
+`data.parents` becomes `system.parents`,
 and each authored key of `data.relations` becomes a key of `system.relations`. The
 reduction happens at build time, and two things are errors naming the note: an
 Address whose type the field does not accept, and two Addresses that reduce to one
@@ -1352,7 +1352,7 @@ Wikilinks contain complete Addresses. For example, `data.parents: [north]` in
 
 SQL queries compare Address-valued fields to complete Addresses. A note's
 `shortcode` is a distinct identity component, so it is not equal to an Address
-stored in `data.parents`, `data.domains` or a governance rank's `lore`. Use the
+stored in `data.parents`, `data.government` or a governance rank's `lore`. Use the
 target's complete identity for that comparison. A stub has no published page
 address; its note identity still contains the package, system, type and shortcode.
 
@@ -1777,7 +1777,7 @@ a warning, flags an asset whose pixel width falls short of what its role's
 largest print slot needs. Both exempt a vector asset, which carries no pixel
 dimensions and no aspect that survives being drawn at a nominal size.
 
-`role: map` also selects a `:::figure` fence's counter — see
+`role: map` also selects a captioned image's counter — see
 [figures and numbered references](../authoring/links-and-markup.md#figures-and-numbered-references).
 A fence whose picture draws an address with that role counts as `Map` rather
 than `Figure`, on every surface that numbers it, because the role is the one
@@ -2006,8 +2006,18 @@ convention rather than declared in a field — see
 
 ### Three states of a note
 
-A note has three states, and two of them are nothing but conventions the format
-already carried.
+Every typed note requires a nonempty body after its closing frontmatter fence.
+An empty or whitespace-only body is an error, regardless of description or
+`tags: [draft]`. This includes `folder` and `homepage` notes. Untyped vault
+scaffolding is excluded. A nonempty body with fewer than 25 prose words warns
+unless tagged `draft`; the tag never exempts an empty body.
+
+The `lint`, `content-index`, `package compile`, `site` and `pdf` commands enforce
+body errors. Write a short beginning and tag it `draft` when work is unfinished.
+
+The internal classification below describes records, including incomplete notes
+that inspection APIs can still read. A **stub** is invalid authored content and
+must receive a body before these commands can publish it.
 
 | State     | Body    | Marker          | Page         | Document                          | Link target |
 | --------- | ------- | --------------- | ------------ | --------------------------------- | ----------- |
@@ -2039,13 +2049,13 @@ same.
 
 | After the fence         | Empty? | What happens                                                    |
 | ----------------------- | ------ | --------------------------------------------------------------- |
-| Nothing, or blank lines | yes    | A stub                                                          |
+| Nothing, or blank lines | yes    | An error, with or without `draft`                               |
 | An HTML comment         | no     | A note with a body that renders to nothing. The lint reports it |
 | A horizontal rule       | no     | The same                                                        |
 | A lone heading          | no     | The same                                                        |
 | `_To be written._`      | no     | The same                                                        |
 
-An HTML comment is deliberately not empty. An invisible marker does not make a valid stub; use an empty body when the note has no prose.
+An HTML comment is deliberately not empty, but an invisible marker does not supply prose. Replace placeholder-only content with written text.
 
 #### What a stub emits
 
@@ -2090,12 +2100,12 @@ What is suppressed with the page is the web address and the link target: a
 wikilink into a stub is refused, and a table cell listing one prints its name as
 plain text rather than as a link.
 
-#### Two types are structural and exempt
+#### Structural classification does not exempt validation
 
-`folder` and `homepage` have no body by design — a folder note's page is a
-generated section index, and the homepage's is the site's front door. An empty
-body on either keeps its address and resolves as **full**, because such a note is
-complete.
+A `folder` note's page is a generated section index, and the homepage is the
+site's front door. The classification helpers retain their addresses and report
+**full** even when their bodies are empty. Validation still rejects an empty
+body for both types.
 
 Every type in the vocabulary declares whether an empty body suppresses its page,
 so adding a type means answering the question rather than inheriting a default.
@@ -2105,8 +2115,8 @@ so adding a type means answering the question rather than inheriting a default.
 `borders.to` and `routes.to` name a place by `Address`, and those are **index
 relations rather than page links**: a border with a stub on the far side is a
 valid statement about the world and resolves. So does `parents` for the
-containment tree and `domains` for tenure — a stub appears in its region's
-`contains` and on its holder's `holdings`, rendered as plain text. What a stub
+containment tree and `government` for governance — a stub appears in its region's
+`contains` and its governing body's `governed_places`, rendered as plain text. What a stub
 cannot be is the target of a wikilink, because a wikilink points at a page.
 
 ### What a note produces
@@ -2242,7 +2252,7 @@ See the [authoring examples](../authoring/links-and-markup.md#footnotes-and-defi
 ```
 
 Any header can end with a braced attribute block, in the same grammar a
-`:::figure` fence and a named block take. Inside the braces:
+caption, fenced div, span and named block take. Inside the braces:
 
 - `#id` names the anchor a link resolves to (only one allowed)
 - `.class1` names a CSS class (any number of classes allowed)
@@ -2327,8 +2337,7 @@ applied to a word in the middle of a sentence.
 **Alt text renders as a caption on no surface.** On the website and in a
 Foundry journal it stays on the `img` element's `alt` attribute alone, and the
 book prints nothing beneath a picture that carries none. A visible label and
-caption are drawn only for a picture wrapped in [a `:::figure`
-fence](#the-figure-fence), and the text drawn is always the fence's own
+caption are drawn only for a picture preceded by [a caption](#captions-and-numbered-references), and the text drawn is always the fence's own
 caption. A title — `![alt](src "title")` — is refused rather than dropped in
 silence: there is one place for those words, the alt text, and a title is not
 it.
@@ -2621,179 +2630,122 @@ the tag and, where the directive restricts one, the type. An empty list under
 an authored heading is how a misspelled tag survives a build, so the
 directive's silence is what is refused rather than its output.
 
-##### The figure fence
+##### Captions and numbered references
 
-`:::figure {#anchor .border}` declares what it numbers and, optionally,
-captions: the fence is the unit the counter counts, not the caption text it
-may or may not carry.
+Write a caption on its own line **before** the item it describes, with a blank line before and after the caption. `:` produces an unnumbered caption; `:@` produces a numbered caption. One or more spaces separate the marker from its text. An optional attribute block at the end accepts an identifier, classes and named attributes:
 
-````markdown
-:::figure {#trade}
+```markdown
+:@ Regional trade routes {#trade .border type=table}
 
-```sql
-SELECT name.full AS "Market" FROM notes WHERE type = 'place'
+| Route | Days |
+| ----- | ---- |
+| North | 4    |
+
+Refer to {{ref "#trade"}} for the market routes.
 ```
 
-///
-Regional trade routes
-:::
+This displays **Table 1: Regional trade routes**; the reference links to **Table 1**. An unnumbered `: Regional trade routes {#trade}` displays only its text, has an anchor, and does not consume a number. An item with no caption remains unnumbered.
 
-Refer to {{ref "#trade"}} for the market routes.
-````
+The caption attaches to exactly the next supported block:
+
+| Next item                            | Inferred type | Numbered label |
+| ------------------------------------ | ------------- | -------------- |
+| Markdown table                       | `table`       | Table          |
+| Image, Markdown or wikilink          | `figure`      | Figure         |
+| SQL fence, including backtick SQL    | `table`       | Table          |
+| Poetry fence                         | `poetry`      | Poem           |
+| Any other code fence                 | `code`        | Code           |
+| Paragraph, quote block or fenced div | `prose`       | Prose          |
 
-The fence displays **Table 1: Regional trade routes** and `{{ref "#trade"}}`
-displays **Table 1** as a link.
-
-**The grammar.** `:::figure` opens the fence, on a line of its own and
-optionally followed by a braced attribute block in the grammar a heading and
-a named block take too. A line of `:::` alone closes it. Between the
-two, the first `///` written alone on a line, read at the top level — outside
-any nested code or poetry fence — divides what the fence holds from its caption; a `///`
-written inside a nested fence is content, not a divider. A second top-level
-`///` is an error, naming the line: a figure holds one caption, so it carries
-one `///` line.
-
-An opening line that is not `:::figure`, optionally followed by one braced
-attribute block and nothing else, is reported at its own line as
-`a figure's attributes are written as {#id .border}`.
-
-**Every part but the fence itself is optional.**
-
-- **No `{#id}`.** The fence is still numbered and drawn; it carries no anchor,
-  so nothing can address it. An id, when written, must be a name unique within
-  the note — a repeat is `duplicate figure id "<id>"` at the fence's opening
-  line, and an id that collides with a heading anchor in the same note is
-  `heading and figure declare the same anchor "<id>"` at the heading's line.
-- **No `///`.** The fence draws its label alone, with no caption beneath it. A
-  `///` with nothing after it before the closing `:::` is an error at the
-  `///` line: a figure's `///` section carries no caption — write no `///` to
-  leave the figure uncaptioned.
-- **No `.border`.** The fence draws without one. `.border` is the only class
-  the construct declares; any other class is reported at the opening line,
-  naming it: a figure takes no such class, and the classes a figure takes
-  are `.border`. A `key="value"` attribute is reported the same way, naming
-  the key: a figure takes an id and classes, nothing else.
-
-**What is never optional.** A fence with nothing between its opening line and
-its `///` or its closing `:::` is `a figure has no contents`, at the opening
-line. An opening `:::figure` with no matching `:::` runs to the end of the
-note and is `a figure needs a closing :::`, also at the opening line, and
-nothing after it is scanned as a second fence.
-
-**The counter is derived, never authored.** The fence's contents decide which
-of six counters it draws from — `Code`, `Table`, `Figure`, `Map`, `Poem`, `Prose` — read from
-the first top-level block inside the fence: a table is `Table`; a fenced `sql`
-block is `Table`, because its rendered output is one; any other fenced or
-indented code block is `Code`; one or more pictures and nothing else is
-`Figure`; a `:::poetry` fence as the first nonblank content is `Poem`; everything else is `Prose`. A poem, table or picture written outside any
-`:::figure` fence draws no label and is counted nowhere. The website and a
-Foundry journal number each counter within the note; the book numbers each
-counter across the book in reading order.
-
-**A heading that would start its own journal page cannot be written inside a
-fence.** An H1, or a heading at any level carrying an `{#anchor}`, is reported
-at its own line inside one: `a heading that starts a page cannot be written
-inside a figure — keep an H1 or an anchored heading at the top level, or drop
-the anchor and the level to stay inside it`.
-
-**The `ref` expression renders a link to a figure's anchor.**
-`{{ref "#thorn"}}` renders "Figure 13"; `{{ref "#thorn" form="full"}}` renders
-the number and the caption; `{{ref "#thorn" form="title"}}` renders the
-caption alone. `form="number"` is the default and may be written explicitly;
-a `form` outside this closed set is reported naming the three. A link written
-inside the figure's own caption contributes only its label text to a `full`
-or `title` reference, because the reference is itself a link, and emphasis
-inside the caption is kept. `form="full"` or `form="title"` aimed at a figure
-with no caption is reported naming the anchor: that form needs a caption, and
-the figure has none. An address naming no figure in the note is reported
-naming the anchor; an address naming another note's figure —
-`{{ref "other-note#anchor"}}` — is reported as addressing a figure this build
-does not resolve outside the note carrying the reference. Only a same-note
-anchor resolves, on the website and in the book.
-
-Foundry gives a `:::figure` fence its own JournalEntryPage. A fence holding
-exactly one picture, captioned in plain text with nothing else — or carrying
-no caption at all — becomes a page of type `image`: the picture is its `src`,
-a caption, when there is one, is `image.caption`, and the page is named for
-the figure's own number. Every other fence becomes a page of type `text`
-instead: a fence grouping more than one picture; an embedded sound, there
-being no audio page type; a fence whose caption carries inline markup —
-emphasis, a link, an embedded icon or image — because `image.caption` is a
-`StringField` with nowhere to render it; and a fence that shares its split
-with prose that follows it, because an `image` page has nowhere to carry that
-prose either. On a `text` page the render is the fence's own content, scanned
-and labelled as the first of its kind on that page alone and then corrected to
-the number the note-wide scan already assigned, so a second figure with no id
-is still named for its true, note-wide number rather than recounted from one.
-
-##### Named blocks
-
-`:::secret`, `:::info` and `:::warn` set a passage apart from the prose around
-it. The opener and the closing `:::` each take a whole line, the content is
-Markdown and renders normally, and the fences stay outside code blocks. An
-empty, nested or unclosed block is an error at its opening line, as is a name
-that is not one of the three.
-
-A braced attribute block may follow the name. It takes an id as `#id`, classes
-as `.class`, and any other attribute as `key="value"`. `title` is reserved and
-supplies the heading; without it a block heads itself **Secret**, **Info** or
-**Warn**. A title carries its own emphasis and nothing else — a tag written
-there is escaped. `id=` and `class=` are refused in favour of `#id` and
-`.class`, and an attribute beginning `on` is refused as an event handler.
+The optional `type` attribute overrides inference and accepts `figure`, `table`, `poetry`, `code`, `prose`, and `example`. `type=example` uses **Example 1**, **Example 2**, and so on. It does not allow an unsupported target. A heading, list, thematic break, another caption or end of document after a caption is an error. Caption markers without separating spaces or caption text are errors too.
+
+Identifiers are optional and must be unique within the note. Classes are unrestricted; `.border` uses the shared border style, while other classes can be styled by the medium. Named attributes use `key=value`, with quoted values for text containing spaces. Use `#id` and `.class` rather than `id=` and `class=`; event-handler attributes are refused.
+
+Each numbered type has its own counter. Websites and Foundry number within a note; books number across their reading order. Unnumbered captions neither display nor consume a number. A map image can retain its asset-derived **Map** classification when no type is specified.
+
+`{{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.
+
+**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.
+
+##### Fenced divs
+
+A bare `:::` opens a div section. An optional attribute block applies to the whole fenced area. A bare `:::` closes the section:
 
 ```markdown
-:::info
+::: {#harbor-note .border lang=en}
 The harbor remains open through winter.
-:::
 
-:::warn {#flood-warning title="Seasonal closure"}
-Spring floods close the eastern road.
+A second paragraph belongs to the same div.
 :::
+```
 
-:::secret {#harbor .wide}
-The harbor master is working for the smugglers.
-:::
+An attribute-bearing opener allows a nested div to be distinguished from the bare closer. Divs carry no automatic title or number; style their classes for the medium. Use a leading caption to caption the entire div. The same attribute grammar is available on named blocks; identifiers, classes and named attributes belong to the entire section. Headings that would start a Foundry journal page cannot split a fenced section.
+
+##### Inline spans
+
+`[inline content]` represents a span. Follow it immediately with an optional attribute block to apply an identifier, classes and named attributes:
+
+```markdown
+The watch wears [a _blue_ sash]{#watch-sash .uniform lang=en}.
 ```
 
-The block's name is the first class on the emitted element and the author's
-classes follow it. **No block carries an inline `style`**, so the appearance is
-a stylesheet's. The base stylesheet styles `section.info` and `section.warn`;
-`section.secret` is left to Foundry, which styles it and owns the reveal control
-on it.
+Inline Markdown remains active inside the span. Bracket spans have lower priority than URL links, image links, reference links, footnotes and wikilinks. A bracketed form immediately preceded by `!`, followed by `(` or another `[`, or beginning with `[[` is not a span, even when the link is unresolved. Ordinary links retain their existing syntax. Escape a bracket when it should be literal, or put examples inside a code span or fence. A span identifier addresses that point in the note; it does not start a journal page.
+
+##### Alerts
 
-In FoundryVTT a block is a section whose first line is its heading, and a
-`secret` is the section Foundry shows to the GM and to owners of the journal:
+Alerts replace the former `:::info` and `:::warn` fences. Start with a special blockquote marker, optionally followed by an attribute block, then write the alert body as a standard blockquote:
 
-```html
-<section class="secret wide" id="harbor">
-  <strong>Secret</strong><br />
-  <p>The harbor master is working for the smugglers.</p>
-</section>
+```markdown
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
 ```
 
-A `secret` that states no id of its own is given one derived from its body, so
-that Foundry can remember the section once a reader reveals it.
+| Marker         | Label     | Appearance                                        |
+| -------------- | --------- | ------------------------------------------------- |
+| `[!NOTE]`      | Note      | Blue rule and `fa-regular fa-message`             |
+| `[!TIP]`       | Tip       | Green rule and `fa-regular fa-lightbulb`          |
+| `[!IMPORTANT]` | Important | Purple rule and `fa-solid fa-circle-info`         |
+| `[!WARNING]`   | Warning   | Amber rule and `fa-solid fa-triangle-exclamation` |
 
-On webpages a block is a disclosure any reader can open, titled in its summary:
+The label and icon sit above the body. Alerts are visible callouts, not expandable sections. Inline Markdown, links, multiple paragraphs, lists and code examples remain available inside the quote. Prefix blank lines within the body with `>` to keep paragraphs in the same alert.
 
-```html
-<details class="secret wide" id="harbor">
-  <summary class="secret">Secret</summary>
-  <p>The harbor master is working for the smugglers.</p>
-</details>
+Attributes follow the marker and apply to the alert:
+
+```markdown
+> [!WARNING] {#flood-warning .seasonal lang=en title="Seasonal closure"}
+> The eastern road closes during spring floods.
+>
+> Use the ridge path instead.
 ```
 
-In a book each block is a coloured box headed by its title. A printed page has
-no reader permissions and no interactive disclosure control, so a `secret` is
-visible there.
+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.
 
-**A secret is a presentation distinction and not access control.** It is in the
-same authored note as the prose around it, and a reader who inspects source or
-generated output may see it.
+##### Secret blocks
 
-**A malformed block does not silence the blocks around it.** It is reported at
-its own line and left as the author wrote it, and every well-formed block in the
-note still renders.
+`:::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**:
+
+```markdown
+:::secret {#harbor-secret title="For the GM"}
+The harbor master is working for the smugglers.
+:::
+```
+
+A secret block can contain alerts and general divs. It cannot contain another secret block. A heading that starts its own journal page cannot split a secret block or general div; use a lower heading without an anchor within the section.
+
+Foundry renders a secret section; the website renders an expandable spoiler, and the book renders a labeled box. An untitled secret takes its normal default title, and a Foundry secret without an id receives an id derived from its body. The presentation does not make published HTML private: deliberately inspecting generated source can reveal its content. Use YAML comments for information that must never be published.
 
 #### Actors
 
@@ -3383,7 +3335,6 @@ rank names the standing, and the standing says.
 | `governance.ranks`   | `Rank[]`                                           | The ranks available to members of the affiliation                                              |
 | `governance.offices` | `Map<name, description \| {description, holders}>` | Official offices and their dated holders                                                       |
 | `seat`               | `Address`                                          | Where the affiliation's authority sits                                                         |
-| `domains`            | `Address[]`                                        | Places over which this affiliation holds sway                                                  |
 | `population`         | `number`                                           | Number of people in the affiliation (precision 2 significant digits).                          |
 | `economy`            | `Address[]`                                        | Economic life: `affiliation` or `lore` Addresses, with an explicit type and no default         |
 | `lore`               | `Address[]`                                        | Lore concerning it — the peoples it draws on, the god a faith venerates, its law, its calendar |
@@ -3443,37 +3394,7 @@ data:
           - { being: being-mara, start: "datefrom vrcal 2 Lusenar 725 VR" }
 ```
 
-**`domains` is territorial, and only territorial.** Seventy-seven divine
-affiliations currently spell `domain:` the other way, holding a deity's sphere of
-influence as prose — _Love, Beauty, and Prosperity_; _Fertility, Agriculture,
-Peace, and Healing_. That sense **folds into `description`**, which those notes
-leave empty in all but one case, and it does not become a field of its own.
-
-A sphere is a characterisation, not a reference. Nothing compiles against it, no
-other note points at it, and rendering it as a list would imply a vocabulary that
-does not exist — whereas `description` is exactly the field for a one-line
-statement of what a thing is. The fuller treatment already has a home: `lore` of
-subType `deity` covers a god's nature, domains, epithets and aspects in prose.
-
-That frees the name for the territorial sense, which earns it: every affiliation
-subType holds sway somewhere, while the divine sense applies to one.
-
-**`domains` names what the affiliation holds directly**, and nothing beneath
-it. A polity whose `domains` names a region holds the region; the settlements
-within it are the region's, reached through its `contains`, and are not
-repeated here. A house holds its manors and names each; the crown holds the
-realm and names the realm. What lies below a holder is answered by the two
-hierarchies together — `place.parents` for where a place sits, and
-`affiliation.parents` for whom a holder answers to — so a subinfeudated manor
-sits in one region by the first and under a lord of another polity by the
-second, and both pages say so.
-
-The website reads `domains` across the package and every fetched index and
-writes the affiliation's page a `holdings` list — every place its `domains`
-names, each entry `{ title, url, type, subType }`, sorted by `subType` then
-`title`, and absent when `domains` names nothing. Every place it names carries
-the affiliation back in `held_by`. Both are derived; a note that writes one has
-it replaced.
+**Governed places are derived from place notes.** Each place names one governing affiliation in `data.government`. The website writes the body's `governed_places` list by resolving those explicit references across local notes and fetched indexes. Each entry is `{ title, url, type, subType }`, sorted by `subType` then `title`; an empty list is omitted. No affiliation-side list supplies government, and neither geographic containment nor organizational parents expands it.
 
 If `sohl` is present, this becomes an `affiliation` item.
 
@@ -3481,7 +3402,6 @@ If `sohl` is present, this becomes an `affiliation` item.
 | ---------------- | ------------------ | ----- |
 | `subType`        | `system.subType`   | NA    |
 | `data.seat`      | `system.seat`      | NA    |
-| `data.domains`   | `system.domain`    | NA    |
 | `data.parents`   | `system.parents`   | NA    |
 | `data.relations` | `system.relations` | NA    |
 
@@ -4263,7 +4183,7 @@ map's prose.
 | `lore`                            | `Address[]`                                         | Lore concerning this place — its peoples, its law, its calendar, its history                              |
 | `parents`                         | `Address[]`                                         | Enclosing places within which this place is located                                                       |
 | `population`                      | `number`                                            | Approximate population (precision 2 significant digits)                                                   |
-| `government`                      | affiliation Address or `null`                       | Governing affiliation; explicit null means complete anarchy. Omission warns only for positive population. |
+| `government`                      | `Address` or `null` (default type: `affiliation`)   | Governing affiliation; explicit null means complete anarchy. Omission warns only for positive population. |
 | `market`                          | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                                                   |
 | `borders`                         | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here                                    |
 | `routes`                          | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                                                        |
@@ -4484,27 +4404,13 @@ than the package that wrote it.
 | `river`         | boat               |
 | `lake`          | boat               |
 
-#### What lies within a place, and who holds it
-
-`parents` states what a place is within; an affiliation's `domains` states
-what it holds. The website reads both across the package and every fetched
-index and writes each place's page two lists, each entry
-`{ title, url, type, subType }` and each absent when empty:
-
-- `contains` — every place whose `parents` names this one, sorted by
-  `subType` then `title`. A region lists its settlements, sites, structures
-  and features; a settlement lists the structures within it.
-- `held_by` — every affiliation whose `domains` names this one, sorted by
-  `title`.
+#### What lies within a place
 
-Both are derived; a note that writes one has it replaced. **`domains` is
-never expanded**: a region held by a polity lists the polity in `held_by`, and
-a settlement within that region lists only the house or order whose `domains`
-names it — its lord's lord is reached through `affiliation.parents`.
+`parents` states what a place is within. The website reads this across the package and every fetched index and writes `contains`: every place whose `parents` names this one, sorted by `subType` then `title`. Each entry is `{ title, url, type, subType }`; the list is omitted when empty. A region lists its settlements, sites, structures and features; a settlement lists its structures. Government never changes this geographical containment.
 
 #### Who governs a place
 
-A place may state its governing affiliation in `data.government`. Use an affiliation Address, either a local shortcode or a fully qualified Address from this package or a fetched dependency:
+A place may state its governing affiliation in `data.government`. The field type is `Address`, with `affiliation` as the default target type when the type is omitted. Use either a local shortcode or a fully qualified affiliation Address from this package or a fetched dependency:
 
 ```yaml
 data:
@@ -4521,20 +4427,15 @@ Write `government: null` for **complete anarchy**. Omitting the key leaves gover
 | Any                   | Explicit `null`     | None; complete anarchy           |
 | Any                   | Affiliation Address | None; the reference must resolve |
 
-These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `domains`, `parents`, containment and capitals do not supply a government. Holdings remain tenure facts; the former unconditional “unheld land” warning is retired.
+These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `domains`, `parents`, containment and capitals do not supply a government. Legacy affiliation `data.domains` is accepted temporarily but ignored. Preserve ownership and influence facts in prose; see [government migration](../guides/government-migration.md).
 
 #### Population figures
 
 `population` is an approximate count, written to two significant digits. A
 place states one, and so does an affiliation — how many people it counts,
 wherever they are. `package-build lint` reads those figures against each other
-and reports four warnings, each named by the phrase its message begins with.
+and reports three warnings, each named by the phrase its message begins with.
 
-- **`over-held land`** — the polities whose `domains` name a place count more
-  people than the place states. A polity subordinate to another polity holding
-  the same place is already inside that polity's figure and is not counted
-  twice. A **settlement is exempt**: the polity of a city-state holds the city
-  and counts the hinterland around it, so its figure is properly the larger.
 - **`over-full region`** — the regions whose `parents` name a place count more
   people than the place states. A region naming both its parent and its
   grandparent counts under the nearer of the two, so a place written into two
@@ -4546,7 +4447,7 @@ and reports four warnings, each named by the phrase its message begins with.
   located at the number the page wrote, and a figure written twice is located
   twice.
 
-The first three are reported on the note's own `data.population`; the fourth
+The first two are reported on the note's own `data.population`; the third
 on the citation.
 
 **A figure is read as a population only where it carries `~`.** That marker is
@@ -4561,7 +4462,7 @@ cent below what it contains is not a finding.
 **An unstated figure is silent.** A place or affiliation with no `population`
 contributes nothing to a sum and is never the subject of a finding, so a
 half-written region is quiet rather than noisy. A fetched index carries
-`population` alongside `parents` and `domains` when its author stated a
+`population` alongside `parents` and `government` when its author stated a
 figure. An older fetched index with no figure remains silent.
 
 **There is deliberately no urban-share rule.** The share of a region's people
@@ -4570,8 +4471,8 @@ settlement layer names the notable places and is complete nowhere, so the ratio
 reports how much of a region has been written rather than how much of it is
 urban.
 
-**A place declares what is true of its ground.** Its governing affiliations
-carry their own `domains`; maps name the place they depict through `data.place`.
+**A place declares what is true of its ground.** It names its governing affiliation
+in `data.government`; maps name the place they depict through `data.place`.
 The place's `lore` links cover its peoples, calendar, law and history. Political
 languages belong to a polity's `sohl.system.commonSkills`, while the note's
 `description` provides its page summary.
@@ -4844,8 +4745,8 @@ the map for the pack it is writing and falls back to `default` when there is no
 such key, so a mistyped `journal:` files the folder wherever the default puts it
 — exactly the hierarchy the key was written to override, and silently.
 
-**A folder note carries no prose.** It is structure, not content, so it produces
-no documentation journal and takes no part in `docEntryTypes`.
+**A folder note requires a body**, like every typed note. Its body does not
+produce a documentation journal or take part in `docEntryTypes`.
 In a compiled Foundry journal, a wikilink to a folder prints its label as text:
 the folder can materialise in several packs and has no single compendium UUID.