@heroiclands/package-build 23.7.1 → 23.9.0

package/docs/authoring/first-note.md

@@ -45,4 +45,4 @@ The full Address is `<package>-note-lore-harbor`; `<package>` comes from `conten
 
 Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.
 
-Every typed note must have a nonempty body after its frontmatter. An empty or whitespace-only body is an error, even with `tags: [draft]` or a description. This includes folder and homepage notes. A nonempty body with fewer than 25 prose words produces a warning unless the note has a `draft` tag. A folder note needs only a nonempty body: any content passes, with or without the tag. See [note states](../reference/format-details.md#three-states-of-a-note).
+Nonempty `data.words` on a language note, or `data.glossary` on a culture or affiliation, supplies content without an authored body. Every other typed note must have a nonempty body after its frontmatter, including folder and homepage notes. An empty or whitespace-only body is otherwise an error, even with `tags: [draft]` or a description. A nonempty body with fewer than 25 prose words produces a warning unless the note has a `draft` tag. A folder note needs only a nonempty body: any content passes, with or without the tag. See [note states](../reference/format-details.md#three-states-of-a-note).

package/docs/authoring/frontmatter.md

@@ -31,7 +31,7 @@ The formatter keeps a collection on one line when the full line is under 100 cha
 
 ## Shared facts and game mechanics
 
-The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, and `banner` fields. A type such as `being` also has its own fields, including `homes` and `affiliations`. `culture` is shared by `being`, `place`, `affiliation`, `lore` and `doc`: it names a `lore` note of `subType: culture`, is required on a `doc` of `subType: settingguide`, and is inherited down `data.parents` by places and affiliations. See [culture in the index](../reference/format-details.md#culture-in-the-index). A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
+The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, `banner`, and `seeAlso` fields. A type such as `being` also has its own fields, including `homes` and `affiliations`. `culture` is shared by `being`, `place`, `affiliation`, `lore` and `doc`: it names a `lore` note of `subType: culture`, is required on a `doc` of `subType: settingguide`, and is inherited down `data.parents` by places and affiliations. See [culture in the index](../reference/format-details.md#culture-in-the-index). A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
 
 A being's `data.archetypes` names the roles it can fill in an adventure. Choose every specific role that fits, such as `entertainer` for a performer or `guildsperson` for someone whose professional training or connections matter. Use `[commoner]` when no specific archetype fits. `commoner` cannot share the list with another value. The [archetype reference](../reference/format-details.md#actors) defines the available roles.
 
@@ -41,6 +41,35 @@ A `sohl:`, `hm3:` or `dnd5e:` block holds values for that Foundry system. Its `s
 
 One body describes the subject for both systems. A being's `{#appearance}` and `{#dossier}` sections feed SoHL Actor `system.appearance` and `system.dossier`, and HM3 Actor `system.description` and `system.biography`. An Item's `{#description}` page becomes a shared JournalEntryPage. Its resolved `@UUID[...]` pointer is stored in SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item with no `{#description}` anchor uses its first page. Other H1 pages remain linkable.
 
+## Suggested reading
+
+Use `data.seeAlso` for deliberate cross-references. Each list entry has a required
+`address` naming another note and an optional `gloss`: a short phrase explaining
+why to follow it. The list keeps the order you write.
+
+```yaml
+data:
+  seeAlso:
+    - address: lore-harborhistory
+      gloss: The founding of the port
+    - address: place-breakwater
+    - address: thalorna-note-lore-searoutes
+      gloss: Routes beyond the bay
+```
+
+Here the harbor history comes first, the breakwater needs no explanation, and
+the sea routes belong to the declared `thalorna` dependency. Write bare Addresses,
+without wikilink brackets or anchors; include the note type, since this field
+has no default type. Local references default to this package and the `note`
+system. A reference must resolve in this package or a declared dependency.
+An unresolved address, duplicate destination, or reference to the note itself
+is an error at that entry's address.
+
+The website places these links and glosses in a **See also** group ahead of
+inferred connections in **Related**. A destination also found among backlinks
+or mentions appears only in See also. Foundry journals and books append a
+**See also** section. An omitted or empty list adds no section or group.
+
 ## Place governments
 
 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:

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

@@ -178,6 +178,20 @@ The harbor master is working for the smugglers.
 :::
 ```
 
+Leave a blank line between a blockquote or alert and the closing `:::`. Without it, Markdown treats the fence as part of the quote and leaves the enclosing block unclosed:
+
+```markdown
+:::secret {title="For the GM"}
+Hidden information.
+
+> [!TIP]
+> Advice for the GM.
+
+:::
+```
+
+`lint`, `markdown` and `format` refuse malformed block and alert syntax, including unclosed divs and unknown alert types. `format` leaves a malformed file unchanged so you can correct the reported opening line before formatting it.
+
 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.
@@ -320,7 +334,7 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 | `glossary`         | One row per entry a culture or an affiliation writes in `data.glossary`, with the `note` it belongs to and the `language` it resolves to.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `language_lineage` | One row per language note and each language it inherits words from through `data.family`, itself included at `depth` 0. Join it to `words` for a language's words with inherited ones.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `dictionary`       | One row per word per language it is listed under, inherited words included, with its `depth`. See [dictionaries and glossaries](#dictionaries-and-glossaries).                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `terms`            | One row per glossary entry, rank or office per note that owns it, with the `cultures` it reaches. See [dictionaries and glossaries](#dictionaries-and-glossaries).                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `terms`            | One row per glossary entry, rank or office per note that owns it, with its `cultures` associations. See [dictionaries and glossaries](#dictionaries-and-glossaries).                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `register`         | One row per name a language note writes in `data.register`, with its `tongue`, `kind`, `gloss` and `why`, its pieces as `built_text`, and the `notes` carrying the name, derived from the index.                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `tongues`          | One row per tag a language note writes in `data.tongues`: `tag`, `meaning` and `tongue_language`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `retired`          | One row per form a language note writes in `data.retired`: `form`, `instead` as a list, and `why`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -826,12 +840,12 @@ See [a language's register, sounds and history](../reference/format-details.md#a
 
 A braced list may follow the language on the opening fence. Four attributes are accepted, and anything else is reported by name.
 
-| Attribute       | Value                               | Default | What it does                                                                                                                                                                                                                           |
-| --------------- | ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `allow-empty`   | `true` or `false`                   | `false` | Whether a query selecting no rows is allowed. A zero-row result is a finding otherwise, because a table that silently prints nothing is the commonest way a query goes wrong unnoticed.                                                |
-| `section-level` | an integer from 1 through 6         | `2`     | The heading level given to each group a `_section` column creates, and to each letter of a dictionary or a glossary.                                                                                                                   |
-| `key`           | `true`, `false` or `only`           | `true`  | Whether a dictionary or a glossary prints its key. `false` leaves it out; `only` prints the key for the fence's rows and no letter or entry, so a page with one `key=false` fence per heading states its key once. Refused on a table. |
-| `layout`        | `table`, `dictionary` or `glossary` | `table` | How the result is set: as a table, as a dictionary of words, or as a glossary of terms — see [dictionaries and glossaries](#dictionaries-and-glossaries).                                                                              |
+| Attribute       | Value                               | Default | What it does                                                                                                                                                                                          |
+| --------------- | ----------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow-empty`   | `true` or `false`                   | `false` | Whether a query selecting no rows is allowed. A zero-row result is a finding otherwise, because a table that silently prints nothing is the commonest way a query goes wrong unnoticed.               |
+| `section-level` | an integer from 1 through 6         | `2`     | The heading level given to each group a `_section` column creates, and to each letter of a dictionary or a glossary.                                                                                  |
+| `key`           | `true`, `false` or `only`           | `true`  | Whether a dictionary or a glossary prints its key. `false` omits the key and any dictionary verb table; `only` prints the key for the fence's rows and no table, letter or entry. Refused on a table. |
+| `layout`        | `table`, `dictionary` or `glossary` | `table` | How the result is set: as a table, as a dictionary of words, or as a glossary of terms — see [dictionaries and glossaries](#dictionaries-and-glossaries).                                             |
 
 ````markdown
 ```sql {allow-empty=true section-level=3}
@@ -859,81 +873,165 @@ See [SQL details](../reference/format-details.md#content-tables) for query optio
 
 ### Dictionaries and glossaries
 
-Two layouts set a result as paragraphs under letter headings rather than as a table. **`layout=dictionary` sets words**, read from the `dictionary` relation: each with its class, its etymology, its senses, numbered where a word's `gloss` lists several, and the notes it is cited from — every note whose prose marks the word in italics. **`layout=glossary` sets terms**, read from the `terms` relation: a culture's or an affiliation's own glossary entries and an affiliation's ranks and offices, each sense tagged with the body or culture it comes from. Each needs the `name`, `senses` and `usage` columns, and a query that leaves one out is reported, naming the column.
-
-**The query decides what appears**, and any note may carry either fence. These are the common ones:
+The build supplies a note's dictionary or glossary from its frontmatter on
+every surface: the site, the Foundry journal and the book.
 
-| What                                      | Layout       | Query                                                                             |
-| ----------------------------------------- | ------------ | --------------------------------------------------------------------------------- |
-| A language's dictionary                   | `dictionary` | `SELECT * FROM dictionary WHERE language = '<the language's Address>'`            |
-| A language's common words, on any page    | `dictionary` | `SELECT * FROM dictionary WHERE language = '<the language's Address>' AND common` |
-| A culture's glossary                      | `glossary`   | `SELECT * FROM terms WHERE list_contains(cultures, '<the culture's Address>')`    |
-| An affiliation's glossary                 | `glossary`   | `SELECT * FROM terms WHERE owner = '<the affiliation's Address>'`                 |
-| The setting's _Dictionary of the Tongues_ | `dictionary` | `SELECT * EXCLUDE (common) FROM dictionary WHERE depth = 0`                       |
-| The setting's _Glossary_                  | `glossary`   | `SELECT * EXCLUDE (common) FROM terms`                                            |
+- **A language note with nonempty `data.words` receives a Dictionary section.** It
+  contains the language's full dictionary as one alphabetical list, with
+  letter headings, each word's field beside it and the key printed once. A
+  language with absent or empty `data.words` receives no Dictionary section.
+- **A culture or affiliation with nonempty `data.glossary` receives a Glossary
+  section.** It contains only the entries that owner declares. Ranks and
+  offices stand in the affiliation's own sections; they enter its glossary
+  only when an explicit glossary entry names them. A note with absent or
+  empty `data.glossary` receives no Glossary section.
 
-A language's dictionary lists the words it inherits through `data.family` beside its own; `depth = 0` lists each word once, under the language that states it. A culture's glossary holds the culture's own terms and the ranks, offices and glossary terms of every affiliation that reaches it. The two setting pages leave out `common`, so they mark no entry: which words are common is a culture's judgement.
+The sections follow the note's authored text. An existing heading with
+`{#dictionary}` or `{#lexicon}` receives the dictionary after its authored
+text; `{#glossary}` does the same for a glossary. The heading and its
+introduction stay in place, with one generated list under it:
 
-The most common Vylari words, on the Vylarian culture's page:
+```markdown
+## Lexicon {#lexicon}
+
+The tongue of Provenzia, whose _solmère_ is its own word.
+```
+
+A dictionary belongs to a language; a glossary belongs to one culture or
+affiliation. A glossary entry belongs for one of three reasons: a common word
+in the owner's core vocabulary, a dictionary word with a context meaning,
+or a phrase, compound or term of art outside the dictionary with its own
+gloss. The [worked culture glossary](../reference/format-details.md#glossary-terms)
+selects `solmère` as a common word, gives `amère` a context meaning and glosses
+`blood-field` as a term outside the dictionary. Its frontmatter supplies the
+whole default Glossary section. There are no setting-wide dictionary or
+glossary pages.
+
+A dictionary noun prints its gender from its existing class and its plural
+where one is available: **marendos** _n. m., pl. marendoi_. An explicit
+word plural wins; otherwise the language's optional `grammar.plural` rule
+replaces the first matching literal ending. The language's optional
+`grammar.verbs` pattern prints once as a small head table, after the key and
+before the letters. Empty verb endings print as "unchanged". Grammar is
+never inherited through `family`, and absent grammar leaves the dictionary
+unchanged. The [worked noun and verb example](../reference/format-details.md#optional-noun-and-verb-forms)
+shows both declarations. Only supplied shapes are checked; words are never
+checked against the rule, and no language must state grammar.
+
+An entry naming a word of its resolved language without a `definition`
+carries the word's dictionary senses and class, with a link to the word's
+entry on its language page. An entry with a `definition` carries that meaning
+instead, retaining its word link and class when it names a dictionary word.
+Ranks, offices and definitions carry their source body or culture beside
+their senses. Common choices belong to each owner: a culture and an
+affiliation using the same language choose independently, and a word may be
+common in one glossary and absent from another. Dictionaries mark nothing
+common.
+
+Public dictionaries omit citations to GM-only notes. `links` checks generated
+tables in the source note's audience: public notes use public rows, and GM
+notes retain GM citations. An authored link from a public note to a GM-only
+note is still reported.
+
+#### Custom views
+
+An `sql` fence with `layout=dictionary` or `layout=glossary` sets a custom view
+of the same relations. A dictionary view reads `dictionary`; a glossary view
+reads `terms`. Each needs the `name`, `senses` and `usage` columns; a query
+that leaves one out is reported, naming the column.
+
+The optional `plural` and `verbs` columns supply noun plurals and the head
+table in a custom dictionary view; `SELECT *` includes both. A projection
+that omits these columns omits that presentation, as omitting `class` omits
+word classes. With the default or `key=true`, each selected language's pattern
+appears once per dictionary result, even when no abbreviation key is needed.
+`key=false` omits both the key and the verb table from a fragment;
+`key=only` prints only the abbreviation key. Separate head-enabled fences
+each print their own tables.
+
+For a custom list of one culture's common entries:
 
 ````markdown
 ## Words Everyone Knows {#common-words}
 
-```sql {layout=dictionary section-level=3}
-SELECT * FROM dictionary WHERE language = 'thalorna-note-skill-vylarilng' AND common
-```
-````
-
-A culture's glossary:
-
-````markdown
-## Glossary {#glossary}
-
 ```sql {layout=glossary section-level=3}
-SELECT * FROM terms WHERE list_contains(cultures, 'thalorna-note-lore-provenzianclt')
+SELECT * FROM terms WHERE owner = 'thalorna-note-lore-provenzianclt' AND common
 ```
 ````
 
-A page that sets several fences, one per heading, states its key once: a `key=only` fence at the head over all the rows the page sets, then `key=false` on each fence below it, so the abbreviations are not repeated under every heading. The `key=only` fence prints the key for its rows and no letter heading and no entry:
+A custom dictionary view can select one field from the language's dictionary:
 
 ````markdown
-## Words {#words}
-
-```sql {layout=dictionary key=only}
-SELECT * FROM dictionary WHERE language = 'thalorna-note-skill-vylarilng' AND depth = 0
-```
-
-### Love and its conduct
+## Love and its conduct
 
-```sql {layout=dictionary key=false section-level=4}
-SELECT d.* FROM dictionary d JOIN words w ON w.language = d.language AND w.form = d.name
-WHERE d.language = 'thalorna-note-skill-vylarilng' AND w.field = 'Love and its conduct'
+```sql {layout=dictionary section-level=3}
+SELECT * FROM dictionary
+WHERE language = 'thalorna-note-skill-provnzlng' AND field = 'Love and its conduct'
 ```
 ````
 
-`key`, whatever its value, sets a dictionary's or a glossary's key, so it is refused on a fence set as a table.
+A custom view with several fences can print its key once: a `key=only` fence
+over all selected rows, then `key=false` on each fence below it. The
+`key=only` fence prints only the abbreviation key. `key`, whatever its value,
+is refused on a fence set as a table. The automatic Dictionary section
+prints its own key once for the full alphabetical list.
 
 Either layout prints, in order:
 
-- **a key**, once, unless the fence sets `key=false`, and nothing else where it sets `key=only`, listing only the abbreviations the result uses — a language's tag, and for words a class or a modifier — each with what it stands for, and the common mark where an entry carries it;
-- **a heading per letter**, at `section-level`, accents taken off and apostrophes skipped, so `'ostal` files under O and `Écuyer` under E;
-- **one paragraph per entry**: `•` for a common entry, the headword in bold, its pronunciation between slashes, its language tag in italics, the senses, and after a dash the notes it is cited from, as links.
+- **a key**, once, unless the fence sets `key=false`, and nothing else where
+  it sets `key=only`, listing the abbreviations the result uses — a language's
+  tag, a word's class or a modifier — each with its expansion; a glossary also
+  explains the common mark where an entry carries it;
+- **a heading per letter**, at `section-level`, accents taken off and
+  apostrophes skipped, so `'ostal` files under O and `Écuyer` under E;
+- **one paragraph per entry**: a glossary's `•` for a common entry, the
+  headword in bold, its pronunciation between slashes, its language tag and
+  word class in italics where present, its senses, and after a dash the notes
+  it is cited from, as links.
 
-A word also carries its class beside the tag and its etymology in brackets:
+A dictionary entry gives its field in italic parentheses and its etymology
+in brackets:
 
 ```markdown
-• **solmère** /sol-MEH-reh/ _n. m._ [fr. Élav. _sólmerë_] Longing; the ache for a time that is gone. — [[thalorna-note-lore-lastshrine|The Song of the Last Shrine]]
+**solmère** /sol-MEH-reh/ _n. m._ (_Love and its conduct_) [fr. Élav. _sólmerë_] Longing; the ache for a person, a place or a time that is gone. — [[thalorna-note-lore-lastshrine|The Song of the Last Shrine]]
 ```
 
-A term carries no class, and each of its senses names its source. A glossary sets the rows sharing a headword and a language as one entry, numbering their senses in the order the rows arrive and printing a sense several bodies give once, with all of them:
+A glossary entry naming a dictionary word uses the word's senses when
+`definition` is absent; a list of dictionary glosses supplies every sense.
+Those senses carry no body label. An entry with a `definition` uses that
+meaning and labels it with the owner, retaining its word link and class
+where it names a dictionary word. On the owner's own page, a sense attributed
+only to that owner omits the repeated label; other bodies and shared senses
+keep their labels. A glossary sets the rows sharing a headword
+and a language as one entry, numbering their senses in query order and
+printing a sense several bodies give once, with all of them:
 
 ```markdown
-**Sworn Knight** **1** (_Duchy of Aubrac_) Holds land of the duke. **2** (_Kingdom of Provenzia_) Holds land of the crown. **3** (_Provenzia_) A knight bound by oath to a lord. — [[thalorna-note-affiliation-duchy|Duchy of Aubrac]], [[thalorna-note-affiliation-kingdom|Kingdom of Provenzia]], [[thalorna-note-lore-provenzianclt|Provenzia]]
-```
-
-The entries are ordered by the layout, not by the query: by letter, then by `name_sort`. **The language tag prints where the entry's language is not the page's own**: a language note's own language, a culture's `data.language`, or the language an affiliation's glossary resolves to. It is the language note's `data.abbreviation`, or its full name where it states none. The etymology never repeats the entry's own language: a borrowed word prints `[fr. Élav. _sólmerë_]`, a built word its pieces each with its gloss, `[_am-_ "love" + _-ère_ "one who"]`, an inherited word its older form, `[*_hur_]` or `[Hel. *_thalass_]`, and a root word its root and pattern. A citation of a note with no published page prints as its name.
-
-A culture's or an affiliation's `data.glossary` shapes both: an entry without a definition marks a word or a rank common, gives it a sort key or a respelling, and lets in a rank whose title is a single word; an entry with a definition replaces the senses of the owner's own rank or office, or is a term of the owner's own. The [format reference](../reference/format-details.md#dictionaries-and-glossaries) gives every column and rule.
+**Sworn Knight** **1** (_Duchy of Aubrac_) Holds land of the duke. **2** (_Kingdom of Provenzia_) Holds land of the crown. **3** A knight bound by oath to a lord. — [[thalorna-note-affiliation-duchy|Duchy of Aubrac]], [[thalorna-note-affiliation-kingdom|Kingdom of Provenzia]], [[thalorna-note-lore-provenzianclt|Provenzia]]
+```
+
+The layout orders entries by letter, then by `name_sort`. **The language tag
+prints where the entry's language is not the page's own**: a language note's
+own language, a culture's `data.language`, or the language an affiliation's
+glossary resolves to. It is the language note's `data.abbreviation`, or its
+full name where unstated. Etymology never repeats the entry's own language:
+a borrowed word prints `[fr. Élav. _sólmerë_]`, a built word its pieces each
+with its gloss, `[_am-_ "love" + _-ère_ "one who"]`, an inherited word its
+older form, `[*_hur_]` or `[Hel. *_thalass_]`, and a root word its root and
+pattern. A citation of a note with no published page prints as its name.
+
+A built piece can name a language element by its `form` or one of its
+`variants`; its `sense` prints beside the piece. An affix can also be named by
+its `front` form. Words and affixes take precedence over elements in the same
+language, and the language is searched before its ancestors. Exact spellings
+are checked before ignoring joining hyphens; case and accents are preserved.
+
+A glossary entry may give its own sort key or respelling. A reference to a
+rank or office inherits its descriptions and admits a title of one word; its
+`common` value belongs to the entry's owner. A definition replaces the senses
+of the owner's own rank or office, or supplies an entry of the owner's own.
+The [format reference](../reference/format-details.md#dictionaries-and-glossaries)
+gives every column and rule.
 
 ## Page lists
 
@@ -973,7 +1071,7 @@ That list names the `lore` notes tagged `key-concept`, grouped by type and alpha
 
 **A tag no page carries is a finding** at the fence's own line, naming the tag it looked for. A misspelled tag is the whole of what goes wrong here, and a heading with an empty list under it is how one goes unnoticed. Write `{allow-empty=true}` where a group that is genuinely empty is intended; the directive then leaves nothing behind rather than an empty list.
 
-A page list names this package's own pages. A **stub** — a note with an empty body — publishes no page, so it joins no list. A note tagged `gm` is listed in Foundry and left out of the website and the book, exactly as it is left out of a content table's relations.
+A page list names this package's own pages. A **stub** — a note with neither an authored body nor automatic lexical content — publishes no page, so it joins no list. A note tagged `gm` is listed in Foundry and left out of the website and the book, exactly as it is left out of a content table's relations.
 
 See [page-list details](../reference/format-details.md#page-lists) for the directive's full behaviour.
 

package/docs/commands.md

@@ -1995,8 +1995,8 @@ package-build lint [root] [--no-references]
 **DESCRIPTION**
 
 Checks a content tree's addresses and frontmatter without compiling anything
-— no LevelDB is opened and no Foundry manifest is needed, so it runs in
-under a second and can gate a commit. Beyond address well-formedness, it
+— no LevelDB is opened and no Foundry manifest is needed. Beyond address
+well-formedness, it
 checks frontmatter against the declared vocabulary and each system's `sohl:`
 / `hm3:` block, the package's charset (so a book can pick a font that covers
 it), that an icon a note writes is one the registry declares, and that
@@ -2012,6 +2012,16 @@ dependencies; exact Item UUID validation remains part of compilation. Reads
 the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
+Content lint computes source positions when it emits findings and shares each
+note's YAML position document across consecutive lookups.
+
+The final summary reports wall time in milliseconds for `index` (collecting
+content records), `SQL` (opening relations and preparing tables, inline queries
+and generated sections), and `validation` (building the link index and running
+the checks). These are elapsed durations from a monotonic clock, including any
+waits within each stage. They are prose summary output, separate from positioned
+findings, and appear whether completed validation passes or reports errors.
+
 **OPTIONS**
 
 | Positional | Type   | Default                        | Description           |
@@ -2172,6 +2182,9 @@ wikilink at all. Also reports a vendored foreign-package content index that
 has drifted out of reach, naming `package-build deps fetch` as the fix. Resolves
 address-valued SoHL system fields declared by the installed schema against this
 package and its declared dependencies.
+An anchored reference to a dependency's readable note must name a prose anchor
+in its fetched content index. A missing section is an error even when the page
+address resolves. Event ids are not prose sections and cannot be wikilink targets.
 Reads the content tree named by `root`, defaulting to `paths.content`, and
 the cached content indexes of any declared dependency; writes nothing.
 
@@ -2332,16 +2345,22 @@ package-build content-index [root] [--out <dir>]
 
 **DESCRIPTION**
 
-Emits this package's note index as JSON Lines — one record per note,
-carrying its full frontmatter plus its place in the tree. Every build
-already walks the tree and parses every note's frontmatter and then throws
-the result away; this publishes that walk so anything outside a build can
-query the content without paying for a second walk. Its own command rather
-than only a build step, because the point is that anyone can regenerate it
-at will — the artifact costs a frontmatter parse, not a build, which is
-also what lets it stay uncommitted. Reads the content tree named by `root`,
-defaulting to `paths.content`; writes `<contentPackage>-metadata.jsonl`
-into `--out`, defaulting to the configured `paths.contentIndex`.
+Emits this package's note index as JSON Lines, carrying full frontmatter,
+tree positions, prose and event anchors, and document targets. Reads the
+content tree named by `root`, defaulting to `paths.content`; writes
+`<contentPackage>-metadata.jsonl`, `<contentPackage>-dictionary.jsonl` and
+`<contentPackage>-terms.jsonl` into `--out`, defaulting to the configured
+`paths.contentIndex`.
+
+The command prepares SQL tables, page lists, automatic sections and scalar
+expressions before publishing their prose targets. Each source uses its own
+audience for prose declarations: public notes use public providers and usage,
+and GM notes use the complete corpus. Native target maps use the compendium's
+complete SQL corpus and expose only declared prose slugs present there, with
+their actual native page targets. Readable item documentation targets its
+documentation journal. An empty published prose-anchor list declares no prose targets,
+including for pages without a Foundry document. Preparation errors leave all
+three output files untouched.
 
 **OPTIONS**
 

package/docs/content-format.md

@@ -9,7 +9,7 @@ subType: userguide
 
 A content package begins with Markdown notes under `assets/content/`. Each note has YAML frontmatter describing its identity and data, followed by prose. Folder names beneath `assets/content/` are for authors; `type`, `subType`, and Addresses determine what the build creates.
 
-Every typed note requires a nonempty body, including drafts, folders and homepages. An empty or whitespace-only body is an error. A nonempty body with fewer than 25 prose words warns unless tagged `draft`; the tag never exempts an empty body. A `folder` note needs only a nonempty body: any content passes, with or without `draft`.
+Nonempty `data.words` on a language note (`type: skill`, `subType: language`), or `data.glossary` on a culture or affiliation, supplies page content without an authored body. Every other typed note requires a nonempty body, including drafts, folders and homepages. An empty or whitespace-only body is otherwise an error. A nonempty body with fewer than 25 prose words warns unless tagged `draft`; the tag never exempts an empty body. A `folder` note needs only a nonempty body: any content passes, with or without `draft`.
 
 Start with [your first note](authoring/first-note.md). It explains the smallest valid note and shows the JournalEntry, web page, book entry, and content-index record made from it. Then use the chapters below in the order your note needs them.
 
@@ -91,6 +91,29 @@ errors, reported at the `ranks` key.
 
 An Item's `{#description}` page is its readable description. The note Address `<package>-note-<type>-<shortcode>#description` resolves to a JournalEntryPage UUID. The build writes the same `@UUID[...]` pointer to SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item note without that anchor uses its first page as the description. Other pages and anchors remain available for links.
 
+## Suggesting another note
+
+State deliberate cross-references in `data.seeAlso`, in reading order:
+
+```yaml
+data:
+  seeAlso:
+    - address: lore-harborhistory
+      gloss: The founding of the port
+    - address: place-breakwater
+    - address: thalorna-note-lore-searoutes
+      gloss: Routes beyond the bay
+```
+
+Each `address` names a whole note; `gloss` optionally explains why to read it.
+The first entry points to the port's history, the second to its breakwater,
+and the third to a note in the declared `thalorna` dependency. An address must
+resolve, and neither a duplicate destination nor the note itself is allowed.
+The site shows the list ahead of other Related links, without repeating their
+destinations. Journals and books append See also; an omitted or empty list adds
+nothing. See [suggested reading](authoring/frontmatter.md#suggested-reading)
+for the Address rules.
+
 ## File and folder names
 
 Every character in the path of a content file or a picture is printable 7-bit ASCII, U+0020 to U+007E. The rule covers each file and folder name under the content tree and under the package's `icons/` and `images/` roots. Letters, digits, spaces, hyphens, underscores, dots and apostrophes are all inside it, so `Knight's_Shield.md` is a valid name. An accented letter, any other non-ASCII character, and a control character are outside it.
@@ -143,6 +166,6 @@ Places, affiliations, lore and beings may name their culture in `data.culture`,
 
 An affiliation may name the trade, temple or order tongue it keeps in its own `data.language`. An affiliation that reaches no culture is a warning, in a tree holding a culture note. A language needs no culture and no affiliation. See [type: affiliation](reference/format-details.md#type-affiliation).
 
-A language note (`type: skill`, `subType: language`) states its words in frontmatter: `data.words` states each word as a map of its form, class, field and gloss — one sense or a list of them, which a dictionary numbers — with its source, its variant forms, the pieces it is built from and a note, beside `data.classModifiers`, `data.fields` and `data.affixes`, each affix with the `kind` it makes, for a given name's ending who the name is `given` to, and the stem closes it is barred after; a zero affix states `zero: true` and no form. The notes a word is cited from are derived, not written: a note cites a word by marking it in italics in its prose, matched by form or a variant with diacritics and case set aside. The language of a word is the note it sits on, and none of it reaches the compiled Item. A daughter language names its parent in `data.family` and reads the parent's words as its own; the `language_lineage` relation joins a language to its ancestors. Classes come from the [master word classes](reference/format-details.md#word-classes). A culture or an affiliation states its own glossary terms in `data.glossary`, and every entry resolves to a language — its own `language`, else the affiliation's, its parents' or its culture's, else the culture's — or is an error at the entry. The `words`, `affixes`, `fields`, `glossary` and `language_lineage` relations hold them for `sql` fences, the `dictionary` relation lists each word under every language that has it, inherited words included, and the `terms` relation each glossary entry, rank and office with the cultures it reaches; a fence sets them with `layout=dictionary` or `layout=glossary`. A language note names the tag a dictionary prints for it in `data.abbreviation`. Every fact a check reads about a language's names, sounds and history is frontmatter too: `data.tongues` and `data.register` (every name the setting gives in the language's reach, the notes carrying each derived from the index), `data.retired`, `data.scope`, `data.sounds` (letters with their place, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule, syllable finals, syllable rules and vowel harmony with each vowel's front partner, the joining of parts, written marks, a root's skeleton vowel and frames, the spellings read past, and named mutations such as wearing and voicing), `data.soundChanges` (named sets of ordered steps), `data.elements` (each standing `opening`, `closing`, `either` or `link`, for one kind of name, with the word it is the stem of and its genitive), `data.roots`, `data.cognates` (with a reconstructed `proto` form), `data.callingNames`, `data.older` (the forms older than the rules), `data.negation` (the negative particle and the mutation it brings) and `data.naming` (how long each class of name runs, the edges names keep that words do not, the element kinds each kind of name draws on, what a place name takes from what it is held from, and the near name), each a relation — `sounds` as `letters`, `edges`, `clusters`, `cluster_groups`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past` and `mutations`, `soundChanges` as `sound_changes`, `callingNames` as `calling_names` — that a fence sets back on the page. A word's citations also come from a note whose name, alias or rank or office title spells it whole. See [a language's words](reference/format-details.md#a-languages-words), [a language's register, sounds and history](reference/format-details.md#a-languages-register-sounds-and-history), [glossary terms](reference/format-details.md#glossary-terms) and [dictionaries and glossaries](reference/format-details.md#dictionaries-and-glossaries).
+A language note (`type: skill`, `subType: language`) states its words in frontmatter: `data.words` states each word as a map of its form, class, field and gloss — one sense or a list of them, which a dictionary numbers — with its source, its variant forms, the pieces it is built from and a note, beside `data.classModifiers`, `data.fields` and `data.affixes`, each affix with the `kind` it makes, for a given name's ending who the name is `given` to, and the stem closes it is barred after; a zero affix states `zero: true` and no form. The notes a word is cited from are derived, not written: a note cites a word by marking it in italics in its prose, matched by form or a variant with diacritics and case set aside. The language of a word is the note it sits on, and none of it reaches the compiled Item. A daughter language names its parent in `data.family` and reads the parent's words as its own; the `language_lineage` relation joins a language to its ancestors. Classes come from the [master word classes](reference/format-details.md#word-classes). A culture or an affiliation states its own glossary entries in `data.glossary`: common words in its core vocabulary, dictionary words with a context meaning, or phrases, compounds and terms of art outside the dictionary with their own gloss. An entry naming a word of its resolved language takes the word's senses and class and links to its language entry; a `definition` supplies the entry's meaning instead. Common marks belong to the glossary's owner. A language note with nonempty `data.words` receives its full Dictionary section automatically: one alphabetical list with field tags and one key. A culture or affiliation with nonempty `data.glossary` receives only its explicitly declared entries in its Glossary section; ranks and offices stand in the affiliation's own sections. A note without the relevant frontmatter receives no such section. All surfaces show these sections after the authored text, or under an existing `{#dictionary}`, `{#lexicon}` or `{#glossary}` heading after its introduction. There are no setting-wide dictionary or glossary pages. Every entry resolves to a language — its own `language`, else the affiliation's, its parents' or its culture's, else the culture's — or is an error at the entry. The `words`, `affixes`, `fields`, `glossary` and `language_lineage` relations hold them for `sql` fences, the `dictionary` relation lists each word under every language that has it, inherited words included, and the `terms` relation each glossary entry, rank and office with its culture associations; a fence sets custom views with `layout=dictionary` or `layout=glossary`. A language note names the tag a dictionary prints for it in `data.abbreviation`. Every fact a check reads about a language's names, sounds and history is frontmatter too: `data.tongues` and `data.register` (every name the setting gives in the language's reach, the notes carrying each derived from the index), `data.retired`, `data.scope`, `data.sounds` (letters with their place, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule, syllable finals, syllable rules and vowel harmony with each vowel's front partner, the joining of parts, written marks, a root's skeleton vowel and frames, the spellings read past, and named mutations such as wearing and voicing), `data.soundChanges` (named sets of ordered steps), `data.elements` (each standing `opening`, `closing`, `either` or `link`, for one kind of name, with the word it is the stem of and its genitive), `data.roots`, `data.cognates` (with a reconstructed `proto` form), `data.callingNames`, `data.older` (the forms older than the rules), `data.negation` (the negative particle and the mutation it brings) and `data.naming` (how long each class of name runs, the edges names keep that words do not, the element kinds each kind of name draws on, what a place name takes from what it is held from, and the near name), each a relation — `sounds` as `letters`, `edges`, `clusters`, `cluster_groups`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past` and `mutations`, `soundChanges` as `sound_changes`, `callingNames` as `calling_names` — that a fence sets back on the page. A word's citations also come from a note whose name, alias or rank or office title spells it whole. See [a language's words](reference/format-details.md#a-languages-words), [a language's register, sounds and history](reference/format-details.md#a-languages-register-sounds-and-history), [glossary terms](reference/format-details.md#glossary-terms) and [dictionaries and glossaries](reference/format-details.md#dictionaries-and-glossaries).
 
 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/design.md

@@ -30,3 +30,34 @@ Passes declare their inputs and outputs so compile order follows dependencies wh
 ## Verification
 
 The command and API references have tests that derive their surfaces from source. The note-format contract lives in structured data and code declarations so editorial changes to Markdown do not change validation. Generated field references are checked against those declarations. Tests check emitted documents as well as input acceptance: a build that exits successfully but drops a value is still wrong. A consumer regression run compares `build/packs-json` across toolchain versions against a real content tree.
+
+The SQL scaling guard runs `prepareTreeSqlTables` over two sizes of a synthetic
+linked note tree, with rewritten shortcodes and references. It profiles each
+executed query through the supplied database, including local and dependency
+relations, inline expressions and generated event sections. DuckDB's JSON
+`EXPLAIN ANALYZE` reports the actual cardinality of file-reader operators before
+downstream filters; these source rows must stay at zero after database creation.
+A direct JSON scan is the positive control for that measurement. In-memory
+scans may grow with the corpus, and elapsed time is not an assertion. Schema
+inspection through `DESCRIBE` has no execution profile and is excluded.
+
+Run the guard with `npm test -- tests/sql-scaling.test.ts`. A controlled local
+change from `CREATE TABLE` to `CREATE VIEW` in `createTableFromFile` must make
+it fail as source rows read per query increase with the larger tree; restore
+the implementation after the probe. The companion relation tests check that
+queries survive source-file removal and enumerate file-reading views.
+
+A compile retains parsed frontmatter, body, raw source and body coordinates in
+its corpus. SQL preparation, document passes, folder pins, event anchors,
+culture inheritance and prose-presence checks consume that shared result.
+The compile guard counts actual Markdown reads and YAML parses for every file
+in its fixture, including documentation and folder notes, and requires one of
+each. Diagnostic positions consume retained source text when supplied.
+
+Standing checks locate only findings they emit. YAML path lookups retain the
+most recently located text's document and line counter; another text replaces
+that single cache entry, so an edited note cannot inherit stale coordinates.
+SQL preparation caches authored answers and stub-inclusive comparisons in
+separate fields per query. Generated event fences read `entries` and `events`
+and skip the comparison; their authored/generated boundary is recorded when
+the sections are appended, independently of query text.

package/docs/diagnostics.md

@@ -170,7 +170,7 @@ package-build.config.yaml:382:64: error: package-build config: `site.sections.be
 
 ## A worked case: the three states of a note
 
-A note with an empty body is a **stub**, and the diagnostics about one show each
+A place note with an empty body is a **stub**, and the diagnostics about one show each
 rule above in turn.
 
 An empty body must be deliberate, so a stub that says nothing about itself is an

package/docs/guides/e2e.md

@@ -128,6 +128,33 @@ for interactive testing. Arguments after `--` are passed to the suite, for
 example `package-build e2e run -- --browser chrome`. A port answering is not
 enough: the harness waits until Foundry's join page shows the world is active.
 
+## Choose a browser
+
+For a Cypress suite, `e2e fast`, `e2e run` and `e2e open` use pinned
+Chrome for Testing **155.0.8059.84** on macOS arm64 and Linux x64. The first run
+downloads it; later runs reuse the cached executable. Each run prints the
+resolved browser and version, and Cypress reports the browser in its header.
+Other suite commands run as declared.
+
+An explicit `--browser` in the configured suite or its extra arguments wins,
+including `--browser=electron`. For example:
+
+```bash
+package-build e2e fast -- --browser electron
+package-build e2e run -- --browser /path/to/chrome
+package-build e2e open -- --browser=chrome
+```
+
+A platform without a configured build requires an explicit installed browser.
+The automatic download needs network access on first use. The cache location is,
+in order: `HL_BROWSER_CACHE`, `browser-cache` beside `FOUNDRYVTT_CACHE`,
+`HL_E2E_ROOT/browser-cache`, or `heroiclands/chrome-for-testing` under the user's
+cache directory (`XDG_CACHE_HOME`, macOS `~/Library/Caches`, otherwise
+`~/.cache`). CI keeps it inside the job's persistent `HL_E2E_ROOT`; point
+`FOUNDRYVTT_CACHE` there too, or set `HL_BROWSER_CACHE` explicitly. Reseeding
+and container teardown leave the browser cache intact. Renovate tracks the
+exact Chrome pin in `e2e.mjs` through the repository's custom datasource.
+
 ## Iterate without reseeding
 
 `fast` rebuilds declared targets, redeploys the full stage, cycles the world,
@@ -196,4 +223,13 @@ container started with the variable set joins the network but keeps the
 environment it was created with; `--recreate` applies `FOUNDRY_AWS_CONFIG`.
 `package-build container <stage> rm` with the variable set removes the server
 and the network along with the container. The server is otherwise left running
-between runs, bucket intact.
+between runs, bucket intact. New and reused servers must answer the S3 HTTP
+health check before Foundry starts; a ready filer alone is insufficient.
+
+Both configuration paths must be readable regular files. When changing
+worktrees, an existing server must bind the identities file from the current
+checkout (symlinks to the same file are accepted). An incompatible or
+uninspectable bind stops the start and names the server and expected path.
+Restore the original checkout to keep its bucket data, or remove only the named
+disposable S3 server with `docker rm -f <container>-s3` and rerun. Removing that
+server discards its bucket data; the tool never removes it automatically.

package/docs/guides/packs.md

@@ -20,7 +20,8 @@ Start with one pack for each document class the notes produce. An Item, Actor,
 Macro, Scene, or Adventure note can also produce a JournalEntry for its prose,
 so a package with those notes generally needs a JournalEntry pack. A missing
 pack for a document a note actually produces is a finding on that note. An
-empty body produces no prose journal and needs no pack for it.
+empty body without automatic Dictionary or Glossary content produces no prose
+journal and needs no pack for it.
 
 ```yaml
 packs: