@heroiclands/package-build 23.9.0 → 23.11.0

package/docs/authoring/first-note.md

@@ -41,6 +41,16 @@ For optional writing suggestions, run `npx package-build prose lint assets/conte
 
 The full Address is `<package>-note-lore-harbor`; `<package>` comes from `contentPackage` in `package-build.config.yaml`. In another note, `[[lore-harbor|Harbor]]` links to it. `[[lore-harbor|]]` asks the renderer to use the target's current name. The pipe is required.
 
+Use another subject's full canonical name at its first prose mention, then
+plain text for later mentions and aliases. Keep a note's own subject in plain
+text. Link indexed subjects even when they are private: the destination's
+audience automatically makes the whole reference a spoiler. Add `.show` only
+to intentionally reveal the reference; it grants no access to the destination.
+For an unwritten subject, use a typed span such as
+`[Aldric Venn]{.name data-type="being/npc"}`. The
+[links and markup guide](links-and-markup.md#marking-names-in-prose) covers
+these rules and separate `[text]{.secret}` spoilers.
+
 ## Grow the note only when needed
 
 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.

package/docs/authoring/frontmatter.md

@@ -25,7 +25,7 @@ data: {}
 
 `description` is the short page summary. `tags` hold draft state and descriptive labels. The note type's classification belongs in `subType` where it is declared. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.
 
-Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Links from untagged notes to GM notes are errors; GM notes may link to one another.
+Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Any note can reference a GM note with an ordinary wikilink. The whole reference is automatically a spoiler; `.show` reveals only that reference, without changing the target's audience or permissions. See [references to secret subjects](links-and-markup.md#references-to-secret-subjects).
 
 The formatter keeps a collection on one line when the full line is under 100 characters. Longer collections use full YAML block form. Run `package-build format --write` to apply key order and collection formatting.
 

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

@@ -23,6 +23,107 @@ A link to a note tagged `draft` retains its target and carries a visible draft c
 
 An HTML comment is an aside to whoever reads the note next, and no surface shows one — the packs and the website emit it into the HTML, where it stays a comment, and a book leaves it out. Write a `markdownlint` pragma or a note about a quoted passage freely. A comment inside a fence or a code span is an example and is printed as written, and a comment that is never closed is an error.
 
+## References to secret subjects
+
+Use an ordinary wikilink for an indexed subject, including a GM-only note:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]
+```
+
+The renderer reads the destination's audience and conceals the entire reference,
+including its label, as a spoiler. Authors do not repeat that audience at each
+reference. A reference to a public subject stays visible. A link to an anchor inside secret content
+conceals its reference too, including a same-note `[[#anchor|label]]`.
+Linking to the public note as a whole does not inherit a section's secrecy.
+
+| Surface | Reference to a secret destination                                                                                                                                      |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Website | An inline show/hide spoiler conceals its label. An omitted GM-only destination produces text without an unusable link. A published secret heading can still be linked. |
+| Foundry | A visible inline spoiler labelled **Secret:** contains the reference. Private pack and page permissions govern whether its destination can be opened.                  |
+| Book    | The reference prints with secret styling and a **Secret:** label. An omitted GM-only destination produces text without a link.                                         |
+
+`.show` removes that automatic spoiler presentation on every surface. Where
+the target is unavailable it still produces text without a link.
+
+To intentionally reveal this reference, add `.show` immediately after the link:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]{.show}
+[[doc-magictruth|The Truth of Magic]]{.show}
+```
+
+`.show` reveals only this reference. It does not publish the destination, change
+its audience or grant Foundry access. It is redundant for a public target.
+Use `[text]{.secret}` when the text itself is a spoiler, independently of any
+destination; see [inline spoilers](#inline-spoilers).
+
+## Marking names in prose
+
+Use `[Name]{.name}` for a name that has no indexed note. Link a name that has
+one, including a private subject; an empty link label uses the indexed full
+name. Introduce another subject with its full canonical name at its first prose
+use. Keep the note's own subject in plain text, and use plain text for later
+mentions and aliases. Bold is emphasis.
+Plain text, including capitalized words, is not searched for names.
+
+```markdown
+[[place-arden|Arden Vale]] stands beside the river. Arden Vale has two gates.
+[Hidden Hand]{.name} keeps watch over the crossing.
+```
+
+To name something that has no note yet, mark it with its type instead of
+creating a placeholder note:
+
+```markdown
+[Ravenmoor]{.name data-type="place/settlement"}
+[Aldric Venn]{.name data-type="being/npc"}
+```
+
+`data-type` is optional. It names a declared [note type and
+subtype](../reference/note-types.md), written as `type` or `type/subType`.
+Enumerated subtypes must belong to that type's list; an open declaration
+accepts a well-formed note subtype, and a type without a subtype declaration
+takes only the bare type. An invalid supplied value is an error at the
+attribute. Site and Foundry spans retain the classes and attribute values;
+the attribute adds no book presentation.
+
+`package-build lint` warns when an indexed name or alias uses `.name`
+instead of a link, when the same name is marked or linked again, or when a
+short form appears before its full name. Only marked names and authored link
+labels count toward these rules. Introduce the full name before an alias such
+as `Arden`, then use plain text for later mentions. Full names and their
+declared aliases count as the same name, including in links to different
+headings. Different labels do not become the same name just because they link
+to the same page.
+
+A name span can sit inside emphasis:
+
+```markdown
+**This is a phrase with [Joe Blow]{.name} in it**
+```
+
+The marked name is `Joe Blow`. Sites and books display `.name` text in bold, including
+inside an emphasized phrase. A whole bold span matching an indexed name or
+alias receives an advisory to mark or link that name; bold containing an
+explicit name span or link needs no such advisory.
+
+These are warnings at each occurrence's `file:line:column`; they do not make
+a valid package fail. The check reads authored prose outside headings,
+tables, infoboxes, code, frontmatter, comments and embeds. See the
+[complete name-marking rules](../reference/format-details.md#marking-names-in-prose).
+
+The index records every actual `.name` span in the authored body, including
+headings, tables, verse and spans inside links. The `names` SQL relation holds
+its visible text, optional type/subtype and source location. Plain prose, bold,
+unmarked link labels and generated content add no rows.
+
+Lint also gives one grouped package advisory for names without a matching
+indexed full name or alias, and for conflicting supplied classifications. It
+lists every use and starts at the earliest reported span. Untyped uses do not
+conflict, and `place` agrees with `place/settlement`; different supplied types
+or different supplied subtypes conflict. These advisories do not fail lint.
+
 ## Journal pages and anchors
 
 Every H1 starts a JournalEntryPage. A lower-level heading with an explicit anchor starts a page too. Use `{#slug}` to make a stable target:
@@ -128,8 +229,43 @@ An attribute-bearing opener allows a nested div to be distinguished from the bar
 The watch wears [a _blue_ sash]{#watch-sash .uniform lang=en}.
 ```
 
+Use `[Ravenmoor]{.name data-type="place/settlement"}` to mark a name with its
+optional declared type; see [marking names](#marking-names-in-prose).
+
 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.
 
+### Inline spoilers
+
+Mark text itself as a spoiler with `.secret`. It can contain inline Markdown or
+combine with a typed name for an unwritten subject:
+
+```markdown
+The key is [under the **third** stair]{.secret}.
+The informant is [Aldric Venn]{.name .secret data-type="being/npc"}.
+```
+
+This marks only the enclosed text; it does not declare a target's audience.
+For indexed subjects, use the ordinary wikilink and let the destination decide
+whether the reference needs a spoiler. `.show` on a wikilink bypasses automatic
+reference concealment; an enclosing authored `.secret` still marks its text.
+
+On the website an inline spoiler has a button to show or hide its content.
+It stays within the surrounding sentence, and links inside it can be followed
+after revealing it. Foundry prints a visible inline `secret` span labelled
+**Secret:**; this span does not withhold its text from players. The book prints
+the text with secret styling and a **Secret:** label; printed text cannot be
+interactively concealed.
+These presentations preserve inline emphasis and the `.name` classification.
+
+Published web HTML contains the spoiler's text. Revealing the spoiler or reading
+the page source exposes it; this is presentation, not access control. GM-only
+destination notes remain absent from public site and book output.
+
+A `.secret` span does not start a journal page or change surrounding text.
+Use a [secret heading](#a-section-players-must-not-read) to withhold a whole
+Foundry page or a [secret block](#secret-blocks) for a passage in a labelled
+section; those retain their own scope and presentation.
+
 ### Alerts
 
 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:
@@ -323,50 +459,51 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 
 ### What a query can read
 
-| Relation           | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `notes`            | Every note except a stub. This is the one to use unless a stub is wanted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `entries`          | Every note, stubs included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `events`           | One row per event a `lore`, `place` or `affiliation` note writes in `data.events`, with `whenSort` to order them by date.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `words`            | One row per word a language note writes in `data.words`, with that note as its `language`, its `position` and what it is built from.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `affixes`          | One row per affix a language note writes in `data.affixes`, with that note as its `language`, its `position`, and each key the affix states: `form` (`NULL` on a zero affix), `zero`, `kind`, `given`, `"where"`, `gloss`, `attaches`, `replaces`, `lengthens`, `front`, `examples`, `barredAfter` and `tones`, then `written`, the form as a table prints it, `∅` for a zero affix.                                                                                                                                                                                                               |
-| `fields`           | One row per field a language note writes in `data.fields`, with that note as its `language`, its `position`, and the field's `name` and what it `holds`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `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 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `scope`            | One row per value of a language note's `data.scope`: the `kind` it is under and the `value`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `letters`          | One row per entry of a language note's `data.sounds.letters`: `letters` as a list, `kind`, `like`, `place` and `tongue`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `edges`            | One row per entry of a language note's `data.sounds.edges`: the `edge` and its `sounds` as a list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `clusters`         | One row per language note stating `data.sounds.clusters`, with its `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `cluster_groups`   | One row per group of a language note's `data.sounds.clusters.groups`: `what`, `clusters` as a list, and `use`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `stress`           | One row per language note stating `data.sounds.stress`, with its `stress`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `finals`           | One row per entry of a language note's `data.sounds.finals`: `final` and `like`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `syllables`        | One row per language note stating `data.sounds.syllables`: each rule a column, the harmony as `harmony_back`, `harmony_front`, `harmony_neutral`, `harmony_neutralAs` and `harmony_partners`, a list of `{ vowel, partner }`.                                                                                                                                                                                                                                                                                                                                                                      |
-| `joining`          | One row per entry of a language note's `data.sounds.joining`: `first`, `second`, `written` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `joins`            | One row per entry of a language note's `data.sounds.joins`: `meeting`, `rule`, `letters` and `"where"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `marks`            | One row per entry of a language note's `data.sounds.marks`: `mark`, `letters`, `kind` and `"limit"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `skeleton`         | One row per entry of a language note's `data.sounds.skeleton`: `second` and `between`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `frames`           | One row per frame of a language note's `data.sounds.frames`: `frame`, `shape`, `class`, `makes` and `examples` as `{ root, form }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `read_past`        | One row per entry of a language note's `data.sounds.readPast`: `written`, `readAs` and `what`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `mutations`        | One row per entry of a language note's `data.sounds.mutations`: `mutation`, `sound`, `becomes` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `sound_changes`    | One row per step of each set in a language note's `data.soundChanges`: the set's `position`, `name`, `from_language`, `to_language` and `takes`, then `step_position`, `step`, `change` and `"where"`.                                                                                                                                                                                                                                                                                                                                                                                             |
-| `elements`         | One row per element of a language note's `data.elements`: `form`, `variants`, `element_position`, `kind`, `sense`, `examples`, `word` and `genitive`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `roots`            | One row per root of a language note's `data.roots`: `root`, `sense` and `field`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `cognates`         | One row per form of each set in a language note's `data.cognates`: the set's `position`, `gloss` and `proto`, the `form_language` and the `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `calling_names`    | One row per closing of a language note's `data.callingNames`: `form`, `doubled`, `usual` and the language's `min_syllables`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `older`            | One row per form of a language note's `data.older`: `form`, `gloss` and `layer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `negation`         | One row per language note stating `data.negation`: its `particle` and `mutation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `name_shapes`      | One row per entry of a language note's `data.naming.shapes`: `of`, `syllables_min`, `syllables_max`, `per_vowel_min` and `per_vowel_max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `name_edges`       | One row per entry of a language note's `data.naming.edges`: `edge`, `sounds` as a list, `vowel` and `of`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `name_draws`       | One row per entry of a language note's `data.naming.draws`: `kind` and `elements` as a list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `held_from`        | One row per entry of a language note's `data.naming.heldFrom`: `source`, `takes`, `clip`, and `genitive` and `elements` as lists.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `near_names`       | One row per worked example of a language note's `data.naming.nearName`: `near`, `given` and the language's `min_syllables`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `market`           | The market scale as three columns — `value`, `name`, `trade` — so a table can print `village` beside the number a note wrote.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `<package>.notes`  | The same relations — `notes`, `entries`, `events`, `words`, `affixes`, `fields`, `glossary`, `language_lineage`, `dictionary`, `terms`, `register`, `tongues`, `retired`, `scope`, `letters`, `edges`, `clusters`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past`, `mutations`, `cluster_groups`, `sound_changes`, `elements`, `roots`, `cognates`, `calling_names`, `older`, `negation`, `name_shapes`, `name_edges`, `name_draws`, `held_from` and `near_names` — for each package this one declares a dependency on, in a schema named for it. |
+| Relation           | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `notes`            | Every note except a stub. This is the one to use unless a stub is wanted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `entries`          | Every note, stubs included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `events`           | One row per event a `lore`, `place` or `affiliation` note writes in `data.events`, with `whenSort` to order them by date.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `names`            | Each authored `.name` span, with its containing NOTE Address, visible text, optional type/subtype and source line/column.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `words`            | One row per word a language note writes in `data.words`, with that note as its `language`, its `position` and what it is built from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `affixes`          | One row per affix a language note writes in `data.affixes`, with that note as its `language`, its `position`, and each key the affix states: `form` (`NULL` on a zero affix), `zero`, `kind`, `given`, `"where"`, `gloss`, `attaches`, `replaces`, `lengthens`, `front`, `examples`, `barredAfter` and `tones`, then `written`, the form as a table prints it, `∅` for a zero affix.                                                                                                                                                                                                                        |
+| `fields`           | One row per field a language note writes in `data.fields`, with that note as its `language`, its `position`, and the field's `name` and what it `holds`.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `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 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `scope`            | One row per value of a language note's `data.scope`: the `kind` it is under and the `value`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `letters`          | One row per entry of a language note's `data.sounds.letters`: `letters` as a list, `kind`, `like`, `place` and `tongue`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `edges`            | One row per entry of a language note's `data.sounds.edges`: the `edge` and its `sounds` as a list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `clusters`         | One row per language note stating `data.sounds.clusters`, with its `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `cluster_groups`   | One row per group of a language note's `data.sounds.clusters.groups`: `what`, `clusters` as a list, and `use`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `stress`           | One row per language note stating `data.sounds.stress`, with its `stress`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `finals`           | One row per entry of a language note's `data.sounds.finals`: `final` and `like`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `syllables`        | One row per language note stating `data.sounds.syllables`: each rule a column, the harmony as `harmony_back`, `harmony_front`, `harmony_neutral`, `harmony_neutralAs` and `harmony_partners`, a list of `{ vowel, partner }`.                                                                                                                                                                                                                                                                                                                                                                               |
+| `joining`          | One row per entry of a language note's `data.sounds.joining`: `first`, `second`, `written` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `joins`            | One row per entry of a language note's `data.sounds.joins`: `meeting`, `rule`, `letters` and `"where"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `marks`            | One row per entry of a language note's `data.sounds.marks`: `mark`, `letters`, `kind` and `"limit"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `skeleton`         | One row per entry of a language note's `data.sounds.skeleton`: `second` and `between`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `frames`           | One row per frame of a language note's `data.sounds.frames`: `frame`, `shape`, `class`, `makes` and `examples` as `{ root, form }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `read_past`        | One row per entry of a language note's `data.sounds.readPast`: `written`, `readAs` and `what`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `mutations`        | One row per entry of a language note's `data.sounds.mutations`: `mutation`, `sound`, `becomes` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `sound_changes`    | One row per step of each set in a language note's `data.soundChanges`: the set's `position`, `name`, `from_language`, `to_language` and `takes`, then `step_position`, `step`, `change` and `"where"`.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `elements`         | One row per element of a language note's `data.elements`: `form`, `variants`, `element_position`, `kind`, `sense`, `examples`, `word` and `joining`.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `roots`            | One row per root of a language note's `data.roots`: `root`, `sense` and `field`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `cognates`         | One row per form of each set in a language note's `data.cognates`: the set's `position`, `gloss` and `proto`, the `form_language` and the `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `calling_names`    | One row per closing of a language note's `data.callingNames`: `form`, `doubled`, `usual` and the language's `min_syllables`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `older`            | One row per form of a language note's `data.older`: `form`, `gloss` and `layer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `negation`         | One row per language note stating `data.negation`: its `particle` and `mutation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `name_shapes`      | One row per entry of a language note's `data.naming.shapes`: `of`, `syllables_min`, `syllables_max`, `per_vowel_min` and `per_vowel_max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `name_edges`       | One row per entry of a language note's `data.naming.edges`: `edge`, `sounds` as a list, `vowel` and `of`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `name_draws`       | One row per entry of a language note's `data.naming.draws`: `kind` and `elements` as a list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `held_from`        | One row per entry of a language note's `data.naming.heldFrom`: `source`, `takes`, `clip`, and `joining` and `elements` as lists.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `near_names`       | One row per worked example of a language note's `data.naming.nearName`: `near`, `given` and the language's `min_syllables`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `market`           | The market scale as three columns — `value`, `name`, `trade` — so a table can print `village` beside the number a note wrote.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `<package>.notes`  | The same relations — `notes`, `entries`, `events`, `names`, `words`, `affixes`, `fields`, `glossary`, `language_lineage`, `dictionary`, `terms`, `register`, `tongues`, `retired`, `scope`, `letters`, `edges`, `clusters`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past`, `mutations`, `cluster_groups`, `sound_changes`, `elements`, `roots`, `cognates`, `calling_names`, `older`, `negation`, `name_shapes`, `name_edges`, `name_draws`, `held_from` and `near_names` — for each package this one declares a dependency on, in a schema named for it. |
 
 Nested frontmatter is addressed exactly as a note writes it: `name.full`, `sohl.weight`, `data.born`. Every Address is a string — the full canonical Address, as in `list_contains(data.parents, 'thalorna-note-place-xerathia')` — whichever package published it. Every note carries a computed `state` column of `full`, `draft` or `stub`. Notes tagged `gm` are absent from the relations on public surfaces.
 
@@ -747,11 +884,11 @@ GROUP BY position, gloss ORDER BY position
 ```
 ````
 
-An element's `kind` keeps one set of elements apart from another, and a place's generic gives its `genitive`:
+An element's `kind` keeps one set of elements apart from another, and a place's generic gives its `joining` form:
 
 ````markdown
 ```sql
-SELECT '`' || form || '`' AS "Generic", sense AS "What it names", coalesce('`' || genitive || '`', '—') AS "In the genitive"
+SELECT '`' || form || '`' AS "Generic", sense AS "What it names", coalesce('`' || joining || '`', '—') AS "Joining form"
 FROM elements WHERE language = 'thalorna-note-skill-nordmalng' AND kind = 'place' ORDER BY position
 ```
 ````
@@ -809,7 +946,7 @@ SELECT source AS "held from",
                   WHEN 'element' THEN array_to_string(list_transform(elements, x -> '`' || x || '`'), ', ')
                   ELSE (CASE takes WHEN 'godName' THEN 'that god''s name' ELSE 'that founder''s given name' END)
                        || coalesce(', clipped to its ' || clip || ' element', '')
-                       || coalesce(', with a genitive ' || array_to_string(list_transform(genitive, x -> '`' || x || '`'), ' or '), '')
+                       || coalesce(', with a joining ending ' || array_to_string(list_transform(joining, x -> '`' || x || '`'), ' or '), '')
        END AS "what stands first"
 FROM held_from WHERE language = 'thalorna-note-skill-nordmalng' ORDER BY position
 ```
@@ -930,8 +1067,8 @@ 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.
+notes retain GM citations. An authored wikilink from a public note to a GM-only
+note is valid and follows the [secret-reference rules](#references-to-secret-subjects).
 
 #### Custom views
 

package/docs/commands.md

@@ -1004,9 +1004,11 @@ scattered entries instead of one.
 
 `group` rewrites the first `## <version>` section of `CHANGELOG.md` in
 place. Within each `### <Bump> Changes` body, every block sharing one bold
-label is merged into a single block for that label — its bullets kept in
-the order they were originally written, an exact-duplicate bullet kept
-once — and the merged blocks are reordered: the unlabelled lead paragraph a
+label is merged into a single block for that label. Prose and bullets are
+retained, with exact duplicate items kept once. Opening paragraphs from
+merged labels combine in source order before their items. Wrapped
+paragraphs, nested item content and literal code stay intact. The merged
+blocks are reordered: the unlabelled lead paragraph a
 changeset writes with no category first, then every label
 [`changelog.labels`](configuration.md#changelog) declares, in the order
 given, then any label absent from that list last, in the order it first
@@ -1501,6 +1503,73 @@ package-build: This repository declares no end-to-end suite to `run`. Name one u
 
 ## Content operations
 
+### `package-build content run <targets..>`
+
+**NAME**
+
+Run selected content checks and outputs from one captured source tree.
+
+**SYNOPSIS**
+
+```text
+package-build content run <targets..> [--no-references] [--pack <name>] [--out <dir>]
+```
+
+**DESCRIPTION**
+
+Choose one or more of `index`, `lint`, `links` and `compile`. The command runs
+each selected target once, in that order, regardless of the argument order.
+They perform the same operations as `content-index`, `lint`, `links` and
+`package compile`. The standalone commands remain available.
+
+The selected operations share captured files, parsed frontmatter, content
+records and exact-source markup scans. Public and complete SQL preparations
+remain separate, as do prose-link checking and native document resolution.
+Each invocation starts a fresh in-memory session; independent commands do
+their own work. Finish dependency fetching, source generation and asset
+preparation before running this command, and start a new invocation after
+changing any input.
+
+All selected preparations finish before the first output is written. If
+source or writer preparation fails, `index` and `compile` leave existing
+index, intermediate JSON and staged packs untouched. Read-only targets still
+report the findings they can produce. An ordinary lint error does not block
+an otherwise successful index or compile target. The command writes no
+persistent source cache.
+
+Selecting `compile` applies the package command's existing package-kind rule
+before any writer. A documentation package can select `index` alone; selecting
+`index compile` reports the compile refusal and leaves its index untouched.
+
+**OPTIONS**
+
+| Option            | Type    | Default                  | Description                                 |
+| ----------------- | ------- | ------------------------ | ------------------------------------------- |
+| `--references`    | boolean | true                     | Check frontmatter references during `lint`. |
+| `--pack` `<name>` | string  | all configured packs     | Restrict `compile` to this pack.            |
+| `--out` `<dir>`   | string  | configured content index | Set the `index` output directory.           |
+
+**EXIT STATUS**
+
+0 when every selected target succeeds, including advisory warnings. 1 when
+arguments or preparation fail, or any selected target reports an error.
+
+**EXAMPLES**
+
+```bash
+package-build content run lint links
+package-build content run index compile
+package-build content run index lint links compile
+```
+
+**SEE ALSO**
+
+`package-build content-index`, `package-build lint`, `package-build links`,
+`package-build package compile`, [Configuration](configuration.md),
+[Programmatic sessions](api.md#enginecontentsession).
+
+---
+
 ### `package-build package <action> [pack] [entry]`
 
 **NAME**
@@ -2012,6 +2081,21 @@ dependencies; exact Item UUID validation remains part of compilation. Reads
 the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
+Name marking is advisory: lint checks explicit `.name` spans and authored link
+labels against the [name-marking
+conventions](authoring/links-and-markup.md#marking-names-in-prose). Plain prose
+is not searched for names. It builds one matcher from the current local and
+dependency names, then
+reports each affected occurrence at its exact source location. These warnings
+also appear when `lint` is selected in `content run`; they do not fail the run.
+
+Lint also emits one grouped package advisory for marked names without an
+indexed full-name or alias match, and for conflicting supplied classifications.
+It lists every source use and is located at the earliest reported span.
+Untyped uses and compatible type/subtype refinements do not conflict.
+An invalid supplied `.name` `data-type` is a located preparation error and
+prevents selected writers. See the same name-marking guide for typed examples.
+
 Content lint computes source positions when it emits findings and shares each
 note's YAML position document across consecutive lookups.
 
@@ -2352,6 +2436,11 @@ content tree named by `root`, defaulting to `paths.content`; writes
 `<contentPackage>-terms.jsonl` into `--out`, defaulting to the configured
 `paths.contentIndex`.
 
+Metadata includes each own note's authored `.name` occurrences under `names`,
+with visible text, nullable type/subtype and original source line/column.
+Local and dependency SQL schemas expose them through `names`; they travel in
+the metadata artifact.
+
 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,

package/docs/content-format.md

@@ -31,6 +31,11 @@ Leading `:` captions describe the next supported block; `:@` captions also numbe
 
 A code fence with language `poetry` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [poetry](authoring/links-and-markup.md#poetry), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans).
 
+Mark a name without a note as `[Name]{.name data-type="being"}`; the optional
+classification uses the declared note vocabulary. The [name-marking
+guide](authoring/links-and-markup.md#marking-names-in-prose) explains its syntax,
+index and grouped lint advice.
+
 Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with
 `{allow-empty=true}` are examples. Inline font glyphs use the package's icon
@@ -47,8 +52,10 @@ for examples and placement in journals, web pages, and books.
 An inline `{{sql "SELECT COUNT(*) FROM notes"}}` expression inserts one scalar query result. Use `{{words (sql "SELECT COUNT(*) FROM notes")}}` for a count in running prose, or `{{digits (sql "SELECT COUNT(*) FROM entries")}}` for grouped numerals. The query must return exactly one row and one column with a nonempty value; a mismatch is a located build error. Prefix `\{{` to show the syntax literally. The [expression reference](reference/format-details.md#dates-and-calendars) describes the helpers and the available SQL relations.
 
 Add `gm` to `tags` for a GM-only note. Public site and book builds omit it;
-Foundry compiles it only into private compendiums. An untagged note cannot link
-to it. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
+Foundry compiles it only into private compendiums. Ordinary wikilinks to it
+conceal the whole reference as a spoiler; `.show` reveals just the reference.
+`[text]{.secret}` marks text itself as a spoiler. Neither changes the target's
+access permissions. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
 explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.
@@ -166,6 +173,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 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).
+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 joining form), `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).