@heroiclands/package-build 22.13.0 → 22.14.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 22.14.0
+
+### Minor Changes
+
+Content notes accept the documented top-level fields, with clear errors for other keys. Formatting keeps those fields in order and writes YAML collections as short lines or full blocks.
+
+## 22.13.1
+
+### Patch Changes
+
+Content authors can keep pinned document identities and compendium placement alongside shared note facts.
+
 ## 22.13.0
 
 ### Minor Changes

package/docs/api.md

@@ -119,28 +119,29 @@ Deterministic document ids, derived by hashing rather than stored, so compile pa
 
 The per-system frontmatter block: how one note feeds more than one game system through properties named after that system (`<system>.system`, `<system>.type`, `<system>.img`, `<system>.items` on actors). Resolves a field's value through the block, the shared top level, and a retiring position in that order, and merges an authored `<system>.system` onto a compiler-built one without disturbing what the builder already wrote.
 
-| Export                      | Signature                                     | Returns                                | Use it when                                                                                   |
-| --------------------------- | --------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                       | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
-| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`             | —                                      | mapping a system-block key to the document property it becomes                                |
-| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                      | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
-| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                     | —                                      | enumerating every key any system block may carry                                              |
-| `setPath`                   | `setPath(target, dotted, value)`              | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
-| `systemBlock`               | `systemBlock(fm, block)`                      | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
-| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`               | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
-| `systemData`                | `systemData(fm, block)`                       | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
-| `blockField`                | `blockField(fm, block, key, defaultValue)`    | the value                              | reading a key from one system's block, falling back to the top level                          |
-| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`    | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
-| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)` | the value                              | reading a property a system block may override, else the shared top-level one                 |
-| `legacyKeyOf`               | `legacyKeyOf(field)`                          | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
-| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                   | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
-| `authoredKey`               | `authoredKey(name)`                           | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
-| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`           | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
-| `systemDataPaths`           | `systemDataPaths(data, prefix)`               | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
-| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`     | `string[]`                             | finding authored paths a system's published schema does not declare                           |
-| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`            | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
-| `claimedPaths`              | `claimedPaths(fields)`                        | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
-| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`             | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
+| Export                      | Signature                                         | Returns                                | Use it when                                                                                   |
+| --------------------------- | ------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                           | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
+| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                 | —                                      | mapping a system-block key to the document property it becomes                                |
+| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                          | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
+| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                         | —                                      | enumerating every key any system block may carry                                              |
+| `setPath`                   | `setPath(target, dotted, value)`                  | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
+| `systemBlock`               | `systemBlock(fm, block)`                          | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
+| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                   | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
+| `systemData`                | `systemData(fm, block)`                           | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
+| `blockField`                | `blockField(fm, block, key, defaultValue)`        | the value                              | reading a key from one system's block, falling back to the top level                          |
+| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`        | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
+| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`     | the value                              | reading a property a system block may override, else the shared top-level one                 |
+| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)` | the value                              | reading a system override, then shared `data`, then a top-level value                         |
+| `legacyKeyOf`               | `legacyKeyOf(field)`                              | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
+| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                       | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
+| `authoredKey`               | `authoredKey(name)`                               | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
+| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`               | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
+| `systemDataPaths`           | `systemDataPaths(data, prefix)`                   | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
+| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`         | `string[]`                             | finding authored paths a system's published schema does not declare                           |
+| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
+| `claimedPaths`              | `claimedPaths(fields)`                            | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
+| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                 | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
 
 ### `engine.codeFences`
 

package/docs/content-format.md

@@ -287,29 +287,57 @@ infoboxes:
 
 ### Frontmatter has three regions
 
-A note's frontmatter divides into three parts, and the difference matters because
-only one of them is open:
+A HeroicLands note has opening YAML frontmatter with nonempty `shortcode` and
+`type` values. Other Markdown files are ordinary Markdown. A note's frontmatter
+has three regions:
 
-| region               | describes                                                                                      | unknown keys               |
-| -------------------- | ---------------------------------------------------------------------------------------------- | -------------------------- |
-| **top level**        | the note as a published artefact — `id`, `type`, `subType`, `shortcode`, `description`, `tags` | **passed through to Hugo** |
-| **`data:`**          | the subject itself — system-agnostic, specific to the note type                                | **an error**               |
-| **`sohl:` / `hm3:`** | the subject as one system's documents                                                          | **an error**               |
+| Region               | Describes                                               | Unknown keys |
+| -------------------- | ------------------------------------------------------- | ------------ |
+| **Top level**        | The note's identity, name, description, and publication | An error     |
+| **`data:`**          | The subject itself, shared by systems                   | An error     |
+| **`hm3:` / `sohl:`** | The subject as one system's documents                   | An error     |
 
-**Top level is deliberately open.** Every key is copied into the generated web
-page's front matter, so an unrecognised key is a Hugo or theme parameter this
-build has no standing to refuse. `description` is the everyday case: it is not a
-document field at all, it is the page's description.
+The complete top-level allowlist, in its required order, is `shortcode`, `name`,
+`type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`. Omit fields that
+do not apply. The first fields of a typical note look like this:
 
-**`data:` is deliberately closed.** It holds the type-specific facts about the
+```yaml
+---
+shortcode: example
+name: { full: Example }
+type: lore
+subType: concept
+description: A short page description.
+tags: [draft]
+data: {}
+sohl: {}
+---
+```
+
+Any other top-level key is an error. To keep an author-only note beside the
+content, comment out its YAML lines with `#`. Comments remain valid YAML text
+and do not become data in the JSONL index, generated pages, or Foundry documents.
+There is no custom site metadata. `description` supplies the page's short
+description; `tags` carries publication and classification tags.
+
+Arrays and objects use one-line YAML flow form when the complete line is under
+100 characters. At 100 characters or more, they use full block form. A multiline
+flow collection is formatted into one of those forms; folded collections are
+not used. `content-build format --write` applies this rule and the top-level
+order without changing the Markdown body.
+
+**`data:` is closed.** It holds the type-specific facts about the
 subject — a weapon's weight, an affliction's transmission, a being's species —
-and every note type declares which keys it may carry. A misspelled key there is a
-finding that names the key you meant; the same misspelling at top level would
-silently become a theme parameter, which is exactly why these cannot live
-together.
+and every note type declares which keys it may carry. A misspelled key is a
+finding in either region.
 
-**Tags are open, except the ones that classify.** `tags:` shares the top level's
-openness: a tag naming a theme or a region — `underworld`,
+Every note type may put a pinned document id in `data.id`, a shared compendium
+route in `data.pack`, a shared folder Address in `data.packFolder`, and source
+details in `data.harnworld`. A system block's `pack` or `packFolder` overrides
+the shared value for that system. A `being` may also describe its social profile
+in `data.social`.
+
+**Tags are open, except the ones that classify.** A tag naming a theme or a region — `underworld`,
 `byzaria`, `riverlands` — is the author's own and this build has no opinion about it.
 A tag that classifies the subject is different, because something queries it. A
 settlement tagged `village` appears in the list of villages and an untagged one
@@ -459,14 +487,11 @@ in-block spelling, and `hm3.system.gender` is the native destination.
 The native destination wins, followed by the in-block value and the shared
 source. Field declarations name both source and destination explicitly.
 
-**A field whose spelling means something else at the note level has no shared
-source.** The fallback assumes the two vocabularies agree about what a name
-means, and they do not always: a note's top-level `title` is the heading its page
-publishes under, while an `affiliation` item's `system.title` is the style of
-address an office carries. Where they diverge, the field declares what the
-top-level key means instead, and the top level stops being read for it — leaving
-`<system>.system.<field>` and the legacy in-block position, which describe the
-document rather than the note. Native species is independent of the shared lore Address in `data.species`.
+**A field without a shared source reads its system declaration.** An
+`affiliation` item's `system.title` is the style of address an office carries;
+the note's heading reads `name.full`. The field reads
+`<system>.system.<field>` and the in-block position, which describe the
+document. Native species is independent of the shared lore Address in `data.species`.
 `subType` has the same meaning at both levels.
 
 **Some of a system's fields are runtime state, and a note may not write any of
@@ -569,8 +594,8 @@ type.
 | ----------------------- | ------------------------- | ---------------------------- |
 | `name.full`             | `name`                    | `name`                       |
 | `data.icon`             | `img`                     | `img`                        |
-| `id`                    | `_id`                     | `_id`                        |
-| `packFolder`            | `folder`                  | `folder`                     |
+| `data.id`               | `_id`                     | `_id`                        |
+| `data.packFolder`       | `folder`                  | `folder`                     |
 | `shortcode`             | `system.shortcode`        | NA                           |
 | `data.templatePriority` | `system.templatePriority` | `flags.hm3.templatePriority` |
 | `actionDefs`            | `system.actionDefs`       | NA                           |
@@ -657,16 +682,20 @@ refused at all four slots: a sound is not art, and a value naming one — `icon:
 audio-thunder`, say — is an error naming the set the slot accepts, never a
 silent fall back to the note's default art.
 
-**Two of them are legal on _every_ note**, whatever its type. `data:` is a
+**These properties are legal on _every_ note**, whatever its type. `data:` is a
 closed container and the per-type vocabularies below are the only lists there
 are, so a key legal everywhere is stated once here rather than repeated in
 twenty-five tables where the one that was mistyped would be the one nobody
 noticed:
 
-| shared `data` property | Values    | Description                                                          |
-| ---------------------- | --------- | -------------------------------------------------------------------- |
-| `icon`                 | `Address` | The document's profile art — an `icon` address, resolved into `img`. |
-| `banner`               | `Address` | The page's hero image — an `image` address.                          |
+| shared `data` property | Values                 | Description                                                          |
+| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `id`                   | `string`               | A pinned document identity.                                          |
+| `pack`                 | `string`               | The shared compendium route.                                         |
+| `packFolder`           | `Address` or pack map  | The shared compendium folder Address.                                |
+| `harnworld`            | `Map<string, unknown>` | HârnWorld source details.                                            |
+| `icon`                 | `Address`              | The document's profile art — an `icon` address, resolved into `img`. |
+| `banner`               | `Address`              | The page's hero image — an `image` address.                          |
 
 `icon` is legal everywhere because most types compile into a document that
 carries one; where a type's passes emit none, the lint says so and the value is
@@ -847,10 +876,11 @@ on any type, and the frontmatter lint never reports it.
 
 #### The pack a note compiles into
 
-`pack` names which configured compendium receives the note's document.
+`data.pack` names which configured compendium receives the note's document.
 
 ```yaml
-pack: items-hm3
+data:
+  pack: items-hm3
 ```
 
 It is deliberately close to the retired `package:` and deliberately not the same
@@ -867,7 +897,8 @@ system: each block the note carries sends its own document where that block
 says, and a note carrying two blocks may place them in two packs.
 
 ```yaml
-pack: items-sohl
+data:
+  pack: items-sohl
 hm3:
   pack: items-hm3
 ```
@@ -898,10 +929,11 @@ and in no compendium — a page of developer documentation, a page about the
 package itself:
 
 ```yaml
+shortcode: architecture
 type: doc
 subType: concept
-shortcode: architecture
-pack: none
+data:
+  pack: none
 ```
 
 A link to such a note resolves everywhere the note is addressable. On the web
@@ -1046,16 +1078,17 @@ none. It is the same principle that turned `folder: ONXsqZAIZr2qzxTb` into
 `packFolder: <address>` above: an opaque derived identity does not belong in
 authored content.
 
-**An authored `id` still wins**, and that is how a document's identity is
+**An authored `data.id` wins**, and that is how a document's identity is
 **pinned**:
 
 ```yaml
-type: miscgear
 shortcode: bowlcer
-id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
+type: miscgear
+data:
+  id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
 ```
 
-A blank `id:` is not a pin — it is a deleted value with the key left behind, and
+A blank `data.id:` is not a pin — it is a deleted value with the key left behind, and
 is treated as absent.
 
 **A rename moves the id, and that is the trade.** The address carries the
@@ -1066,85 +1099,28 @@ identity across one pins its `id`, which is what the pin is for. One diagnostic
 narrows — `content-build` tells a **rename** from a **withdrawal** by matching
 document ids across releases, and for an unpinned note both sides now move
 together. It never reports a _wrong_ successor, and it stays exact for a pinned
-note; for the rest, the note **declares** the rename (below).
+note; for the rest, the diff reports the vacated address.
 
 **A note with no address gets no id, and no document.** `type` and `shortcode`
 are what a note is addressed by, so a note missing either cannot be filed and
 the build refuses it by that name rather than by a missing `id:`.
 
-#### Declaring a rename
-
-A note names the shortcode it used to be published under:
-
-```yaml
-type: weapongear
-shortcode: Taburi
-renamedFrom: Tabri
-```
-
-`(type, shortcode)` is a **published interface** — every satellite that declares
-`itemCatalog: true` assembles its beings out of those addresses — so renaming a
-shortcode breaks other repositories, and `content-build addresses diff` exists to
-say so before a release does. To be useful it has to name where the address
-_went_, and since ids are derived it can no longer work that out for an unpinned
-note: both sides of the match move together, and the rename reads as a
-withdrawal.
-
-**Pinning an `id` needs foresight; a declaration needs only hindsight.** A pin
-has to be written _before_ the rename, by an author who does not yet know they
-will make one. An author who has just renamed a shortcode knows exactly what the
-old one was, and that is the only moment anyone does — so this is the key to
-reach for, and `id:` stays what it is for: keeping a document's identity across
-the rename, which is a different question from explaining it.
-
-**It takes one shortcode or a list**, because renames chain: the diff runs
-against a released baseline, and a shortcode may have been renamed more than once
-since. List every name the baseline might still know it by.
-
-```yaml
-shortcode: Taburin
-renamedFrom:
-  - Tabri
-  - Taburi
-```
+#### Address changes
 
-**It is transient.** Once every baseline a build is compared against post-dates
-the rename, the declaration has nothing left to say and should be deleted. That
-is what separates it from an `id:` pin, which is permanent.
-
-**One key per note, at the top level**, however many systems the note compiles
-into: a shortcode is the note's rather than a system block's, so a note carrying
-`sohl:` and `hm3:` blocks compiles two documents that share one shortcode, and
-one declaration covers both.
-
-**What a declaration changes is what the diagnostic can say, not what it says
-about you.** A finding reports which of the two joins it had, because they are
-not equally checkable — a matched id is a fact a reader can verify in both
-artefacts, while a declaration is the author's word:
-
-```text
-since sohl@0.8.2, weapongear:Tabri is no longer published; the note now
-published as weapongear:Taburi declares it was renamed from Tabri. Every
-package that resolves weapongear:Tabri breaks when it moves past sohl@0.8.2
-```
-
-A rename that is neither pinned nor declared is still reported as a
-**withdrawal**. Nothing infers a successor from a similar-looking string: a wrong
-one sends the reader to the wrong fix, which is worse than saying nothing.
-
-`content-lint` holds a declaration to the same rules a current address is held
-to. An entry must be a well-formed shortcode, must not be the note's own, and
-must name an address the package actually **vacated** — an entry naming an
-address some note still publishes is refused, as are two notes claiming one
-predecessor, since an address had one holder and so has one successor. A repeat
-of the same entry is a warning; the declaration still works.
+`(type, shortcode)` is a published interface. Other packages can link to it or
+use it as an Item model, so changing either part requires those references to
+change too. `content-build addresses diff` compares the package with a released
+baseline and reports addresses whose published documents are absent. A pinned
+`data.id` preserves document identity across a shortcode change; it does not
+keep the old address available for links.
 
 #### The compendium folder
 
 A note says which folder of its pack it lands in:
 
 ```yaml
-packFolder: poisonsandtoxins # a folder note's address
+data:
+  packFolder: poisonsandtoxins # a folder note's address
 ```
 
 **`packFolder` is a folder note's address** — an ordinary address, resolved the
@@ -2481,6 +2457,7 @@ Generates a living (or undead, or spirit) being.
 | `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                       |
 | `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — `[]` where none apply; `null` is an error. |
 | `occupation`                | `string`                                       | Name of the character's occupation                                                               |
+| `social`                    | `Map<string, unknown>`                         | The being's social profile                                                                       |
 | `stations`                  | `Address[]`                                    | Name of the stations the character belongs to                                                    |
 | `lore`                      | `Address[]`                                    | Lore concerning this being — the people it is of, the standing it holds, the law it lives under  |
 | `homes`                     | `Address[]`                                    | Place the being calls home                                                                       |
@@ -2743,9 +2720,9 @@ no Foundry document: it is a page and nothing else.
 It declares a `shortcode` — conventionally `root` — because that is what a
 link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and it
 resolves to `/<package>/`. The shortcode names the page in links; its address
-is the package root. `title` defaults to `packageBuild.manifest.title`; a
-`description` and a `banner` are read by the theme's hero; any other
-top-level key is passed through to the page as a theme parameter.
+is the package root. The page heading reads `name.full` and defaults to
+`packageBuild.manifest.title`. `description` supplies the page's short
+description.
 
 The page is its body, published verbatim: no wikilink is resolved on it and
 no table expanded, so its links are markdown links, package-relative
@@ -2753,9 +2730,8 @@ no table expanded, so its links are markdown links, package-relative
 written here and is not generated anywhere — it is a `doc` note carrying a
 content table, linked from this page like any other.
 
-Two top-level keys are refused, because neither decides anything on a page:
-`id`, the Foundry document id a compendium UUID is built from, and `landing`,
-a card block — the homepage is a page with a body, rendered as one.
+The homepage uses the same top-level allowlist as every addressed note. It has
+no Foundry document id; a pinned `data.id` has no role on this type.
 
 ### type: vehicle
 
@@ -2981,14 +2957,10 @@ mapping for a field no schema declares is the drift these tables exist to catch.
 likewise absent here: they are filled on an embedded membership, never from a
 catalogue note's `data:`.
 
-**`system.title` is not the note's `title`.** The two are unrelated quantities
-that share a spelling. A note's top-level `title` is _the title of the note_ —
-the heading its page is published under; an affiliation's `system.title` is _the
-style of address the office carries_, Ajaw or Warden, which a being holds by
-virtue of its rank. So the top-level key is **not** a shared source for this
-field, and a note that writes one is stating its own heading and nothing else
-. Author the style of address on the membership — the `system.title` of the
-entry in a being's `sohl.items` — or, on a catalogue note that genuinely carries
+**`system.title` is the style of address the office carries**, Ajaw or Warden,
+which a being holds by virtue of its rank. The note's page heading reads
+`name.full`. Author the style of address on the membership — the `system.title`
+of the entry in a being's `sohl.items` — or, on a catalogue note that carries
 one, at `sohl.system.title`.
 
 ### type: affliction

package/engine/folder-notes.mjs

@@ -274,7 +274,8 @@ export function collectFolderNotes(notes, pkg) {
 
         const { parent, color } = folderFields(fm);
         const address = folderAddress(pkg, shortcode);
-        const authoredId = fm.id == null ? "" : String(fm.id).trim();
+        const pinnedId = fm.data?.id ?? fm.id;
+        const authoredId = pinnedId == null ? "" : String(pinnedId).trim();
 
         folders.push({
             shortcode,

package/engine/frontmatter-lint.mjs

@@ -55,6 +55,7 @@
  */
 
 import { isAddressTuple } from "./address.mjs";
+import { authoredNoteKeys, NOTE_TOP_LEVEL_KEY_SET } from "./note-frontmatter.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
 import {
@@ -1443,6 +1444,24 @@ export function lintNote(
         });
     }
 
+    for (const key of authoredNoteKeys(raw())) {
+        if (NOTE_TOP_LEVEL_KEY_SET.has(key)) continue;
+        const position = positionInFrontmatter(raw(), key, undefined, { topLevel: true });
+        if (
+            findings.some(
+                (finding) => finding.severity === "error" && finding.line === position.line,
+            )
+        ) {
+            continue;
+        }
+        findings.push({
+            file: note.file,
+            ...position,
+            severity: "error",
+            message: `unknown top-level frontmatter key ${JSON.stringify(key)}; use shortcode, name, type, subType, description, tags, data, hm3, or sohl`,
+        });
+    }
+
     // The type's charset, before anything that looks the type up. A
     // hyphenated type is unaddressable, and every lookup below would report it
     // as a type nobody declared — true, but not the reason, and it would send

package/engine/frontmatter.mjs

@@ -348,7 +348,7 @@ export function parseValueDesc(raw) {
 /**
  * The compendium folder a note names.
  *
- * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * `data.packFolder` is a folder note's **address**
  * (`folder-poisonsandtoxins`), resolved through the address index the whole
  * build shares. The `folder:` Foundry-id spelling this function once read
  * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
@@ -372,7 +372,7 @@ export function parseValueDesc(raw) {
  *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
-    const asAddress = sohlField(fm, "packFolder", null);
+    const asAddress = fm?.sohl?.packFolder ?? fm?.data?.packFolder ?? fm?.packFolder ?? null;
     if (asAddress != null && asAddress !== "") return { value: asAddress, isAddress: true };
     return { value: null, isAddress: true };
 }

package/engine/homepage.mjs

@@ -340,8 +340,8 @@ function positionOfType(file) {
  * The one defaulted value on the page, and it defaults to the package's own
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
- * authored `title` wins, because a front page is allowed to greet a reader
- * differently from a package browser.
+ * authored `name.full` wins, because a front page may greet a reader
+ * differently from a package browser. A top-level `title` is also readable.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -351,7 +351,7 @@ function positionOfType(file) {
  * @returns {string} The title.
  */
 export function homepageTitle(fm, config) {
-    const authored = fm?.title;
+    const authored = fm?.name?.full ?? fm?.title;
     if (typeof authored === "string" && authored.trim()) return authored;
     const manifest = /** @type {Record<string, unknown>|undefined} */ (
         config?.packageBuild?.manifest

package/engine/item-compiler.mjs

@@ -64,7 +64,12 @@ import { documentSubtype, subtypeRow } from "./document-subtypes.mjs";
 // The note-level `<system>:` block: `<system>.system` onto the document's
 // `system` verbatim, and `<system>.img` / `.effects` / `.flags` overriding
 // their shared top-level forms for this system alone.
-import { blockField, blockProperty, claimedPaths, mergeSystemData } from "./system-block.mjs";
+import {
+    blockDataProperty,
+    blockProperty,
+    claimedPaths,
+    mergeSystemData,
+} from "./system-block.mjs";
 // The other direction of the same declaration: a field the *document* writes in
 // play, which a note may not author and the builder does not emit.
 import { assertNoDerivedFields } from "./derived-fields.mjs";
@@ -379,7 +384,7 @@ export class SystemItemCompiler extends BasePackCompiler {
         // one spelling: `packFolder` names a folder note by its address, the
         // `folder:` id spelling having been retired with the per-pack YAML it
         // resolved against.
-        const folder = this.folderResolver(blockField(fm, system, "packFolder", null), {
+        const folder = this.folderResolver(blockDataProperty(fm, system, "packFolder", null), {
             isAddress: true,
         });
 

package/engine/map-places.mjs

@@ -207,7 +207,9 @@ export function placesFromRecords(records, { contentBase, base }) {
                 folder: record.file?.folder ?? "",
                 package: String(record.package ?? ""),
                 local: true,
-                hasPackFolder: Object.hasOwn(record, "packFolder"),
+                hasPackFolder:
+                    Object.hasOwn(record.data ?? {}, "packFolder") ||
+                    Object.hasOwn(record, "packFolder"),
             });
         } else if (record.type === "affiliation" && record.subType === "polity") {
             polities.push({

package/engine/note-format.mjs

@@ -0,0 +1,100 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import YAML from "yaml";
+import { NOTE_TOP_LEVEL_KEYS } from "./note-frontmatter.mjs";
+
+const MAX_FLOW_LINE = 99;
+
+/**
+ * Format one addressed note's YAML without changing its Markdown body.
+ * Invalid YAML remains the YAML linter's finding.
+ *
+ * @param {string} markdown - The complete Markdown source.
+ * @returns {string} The source with canonical frontmatter.
+ */
+export function formatNoteFrontmatter(markdown) {
+    const match = markdown.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)([\s\S]*)$/);
+    if (!match) return markdown;
+    const [, opening, source, closing, body] = match;
+    const document = YAML.parseDocument(source, { keepSourceTokens: true });
+    if (document.errors.length || !YAML.isMap(document.contents)) return markdown;
+    const root = document.contents;
+    const values = Object.fromEntries(
+        root.items.map((pair) => [String(pair.key?.value), pair.value]),
+    );
+    if (!nonempty(values.shortcode) || !nonempty(values.type)) return markdown;
+
+    const order = new Map(NOTE_TOP_LEVEL_KEYS.map((key, index) => [key, index]));
+    const rank = (key) => order.get(key) ?? NOTE_TOP_LEVEL_KEYS.length;
+    root.items.sort((left, right) => {
+        const a = String(left.key?.value);
+        const b = String(right.key?.value);
+        const difference = rank(a) - rank(b);
+        return difference;
+    });
+    for (const pair of root.items) {
+        const key = String(pair.key?.value);
+        formatCollection(pair.value, key.length + 2, 0);
+    }
+    const formatted = document.toString({ lineWidth: 0, flowCollectionPadding: false }).trimEnd();
+    return `${opening}${formatted}${closing}${body}`;
+}
+
+function nonempty(node) {
+    return YAML.isScalar(node) && typeof node.value === "string" && node.value.trim() !== "";
+}
+
+/** Format nested collections before testing the enclosing line. */
+function formatCollection(node, prefix, depth) {
+    if (!YAML.isMap(node) && !YAML.isSeq(node)) return;
+    if (YAML.isMap(node)) {
+        for (const pair of node.items) {
+            formatCollection(
+                pair.value,
+                2 * (depth + 1) + String(pair.key?.value).length + 2,
+                depth + 1,
+            );
+        }
+    } else {
+        for (const item of node.items) formatCollection(item, 2 * (depth + 1) + 2, depth + 1);
+    }
+    if (hasBlockScalar(node) || hasAlias(node)) {
+        node.flow = false;
+        return;
+    }
+    node.flow = true;
+    const candidate = new YAML.Document(node)
+        .toString({
+            lineWidth: 0,
+            flowCollectionPadding: false,
+        })
+        .trimEnd();
+    if (candidate.includes("\n") || Array.from(candidate).length + prefix > MAX_FLOW_LINE) {
+        node.flow = false;
+    }
+}
+
+function hasBlockScalar(node) {
+    if (YAML.isScalar(node)) return node.type === "BLOCK_LITERAL" || node.type === "BLOCK_FOLDED";
+    if (YAML.isMap(node)) return node.items.some((pair) => hasBlockScalar(pair.value));
+    if (YAML.isSeq(node)) return node.items.some(hasBlockScalar);
+    return false;
+}
+
+function hasAlias(node) {
+    if (YAML.isAlias(node)) return true;
+    if (YAML.isMap(node)) return node.items.some((pair) => hasAlias(pair.value));
+    if (YAML.isSeq(node)) return node.items.some(hasAlias);
+    return false;
+}

package/engine/note-frontmatter.mjs

@@ -0,0 +1,33 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import YAML from "yaml";
+
+/** The complete ordered top-level vocabulary for addressed content notes. */
+export const NOTE_TOP_LEVEL_KEYS = Object.freeze([
+    "shortcode",
+    "name",
+    "type",
+    "subType",
+    "description",
+    "tags",
+    "data",
+    "hm3",
+    "sohl",
+]);
+
+/** Membership test for the top-level vocabulary. */
+export const NOTE_TOP_LEVEL_KEY_SET = new Set(NOTE_TOP_LEVEL_KEYS);
+
+/** Return authored keys from an opening YAML frontmatter map. */
+export function authoredNoteKeys(markdown) {
+    const source = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+    if (source === undefined) return [];
+    const document = YAML.parseDocument(source);
+    if (document.errors.length || !YAML.isMap(document.contents)) return [];
+    return document.contents.items.map((pair) => String(pair.key?.value));
+}

package/engine/note-ids.mjs

@@ -105,7 +105,7 @@ function text(value) {
  */
 export function noteDocId(fm, { pkg, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS } = {}) {
     if (!fm || typeof fm !== "object") return undefined;
-    const pinned = text(fm.id);
+    const pinned = text(fm.data?.id) ?? text(fm.id);
     if (pinned) return pinned;
     const type = text(fm.type);
     const shortcode = text(fm.shortcode);

package/engine/note-vocabulary.mjs

@@ -277,6 +277,29 @@ const TOKEN_ICON = Object.freeze({
  * @type {readonly DataFieldSpec[]}
  */
 export const SHARED_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "id",
+        ...TEXT,
+        describe: "A fixed document identity when the derived identity is unsuitable.",
+    }),
+    Object.freeze({
+        name: "pack",
+        ...TEXT,
+        describe: "The shared compendium route, with a system block overriding it.",
+    }),
+    Object.freeze({
+        name: "packFolder",
+        ...LINK_BY_PACK,
+        ref: "folder",
+        accepts: ["folder"],
+        describe: "The shared compendium folder Address, with a system block overriding it.",
+    }),
+    Object.freeze({
+        name: "harnworld",
+        shape: "map",
+        kind: "map",
+        describe: "HârnWorld source details shared by every system.",
+    }),
     Object.freeze({
         name: "icon",
         ...LINK,
@@ -605,6 +628,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         // package's declared present compute — see `engine/being-age.mjs`.
         check: checkBeingAge,
         data: Object.freeze([
+            { name: "social", shape: "map", kind: "map", describe: "The being's social profile." },
             TOKEN_ICON,
             TEMPLATE_PRIORITY,
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },

package/engine/pack-router.mjs

@@ -82,7 +82,7 @@
 
 import { NO_PACK, packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
-import { blockProperty, systemBlock } from "./system-block.mjs";
+import { blockDataProperty, systemBlock } from "./system-block.mjs";
 
 /**
  * A note that cannot be routed to a pack. Thrown rather than returned so no
@@ -131,7 +131,9 @@ export { NO_PACK };
  */
 export function declaresNoPack(fm, system) {
     const declared =
-        system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
+        system === undefined ?
+            (fm?.data?.[PACK_FIELD] ?? fm?.[PACK_FIELD])
+        :   blockDataProperty(fm, system, PACK_FIELD);
     return declared === NO_PACK;
 }
 
@@ -270,7 +272,9 @@ export function createPackRouter(packs) {
         const inBlock = system === undefined ? undefined : systemBlock(fm, system)?.[PACK_FIELD];
         const authoredInBlock = inBlock != null && inBlock !== "";
         let declared =
-            system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
+            system === undefined ?
+                (fm?.data?.[PACK_FIELD] ?? fm?.[PACK_FIELD])
+            :   blockDataProperty(fm, system, PACK_FIELD);
         // The declaration names where the note's *own* document goes. A pass
         // writing a document derived from it — an item's prose becoming a
         // JournalEntry — is not what the author was addressing.

package/engine/prose-lint.mjs

@@ -33,6 +33,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { formatNoteFrontmatter } from "./note-format.mjs";
 
 import {
     MARKDOWNLINT_CONFIG,
@@ -202,7 +203,7 @@ export async function checkFormatting(root, opts = {}) {
                 let formatted = source;
                 let converged = false;
                 for (let pass = 0; pass < MAX_FORMAT_PASSES; pass += 1) {
-                    const next = await prettier.format(formatted, options);
+                    const next = formatNoteFrontmatter(await prettier.format(formatted, options));
                     if (next === formatted) {
                         converged = true;
                         break;
@@ -236,7 +237,7 @@ export async function checkFormatting(root, opts = {}) {
                 continue;
             }
 
-            if (!(await prettier.check(source, options))) {
+            if (formatNoteFrontmatter(await prettier.format(source, options)) !== source) {
                 findings.push({
                     file,
                     severity: "error",

package/engine/system-block.mjs

@@ -361,6 +361,25 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
     return shared === undefined || shared === null ? defaultValue : shared;
 }
 
+/**
+ * A system override followed by a shared `data:` value. The top-level value
+ * remains readable while content repositories move their authored fields.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+    const declared = systemBlock(fm, block)?.[key];
+    if (declared !== undefined && declared !== null) return declared;
+    const shared = isMapping(fm?.data) ? fm.data[key] : undefined;
+    if (shared !== undefined && shared !== null) return shared;
+    const legacy = isMapping(fm) ? fm[key] : undefined;
+    return legacy === undefined || legacy === null ? defaultValue : legacy;
+}
+
 /**
  * The key a field is authored at **inside** a system block — step 2.
  *

package/hm3/actors.mjs

@@ -63,7 +63,12 @@ import {
 // The note-level `hm3:` block: `hm3.system` onto the document's `system`
 // verbatim, and `hm3.img` / `hm3.items` / `hm3.effects` / `hm3.flags`
 // overriding their shared top-level forms for this system alone.
-import { blockField, blockProperty, mergeSystemData } from "../engine/system-block.mjs";
+import {
+    blockDataProperty,
+    blockField,
+    blockProperty,
+    mergeSystemData,
+} from "../engine/system-block.mjs";
 
 /**
  * Native HM3 facts shared by its actor subtypes.
@@ -324,7 +329,7 @@ export class Hm3Actors extends SystemActorCompiler {
         // by its address. This pass once read only the Foundry id, so an HM3
         // tree could not file an actor by address at all — which its own sweep
         // needs; the id spelling is retired outright.
-        const folder = this.folderResolver(blockField(fm, block, "packFolder", null), {
+        const folder = this.folderResolver(blockDataProperty(fm, block, "packFolder", null), {
             isAddress: true,
         });
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.13.0",
+    "version": "22.14.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/frontmatter.d.mts

@@ -149,7 +149,7 @@ export function parseValueDesc(raw: any): {
 /**
  * The compendium folder a note names.
  *
- * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * `data.packFolder` is a folder note's **address**
  * (`folder-poisonsandtoxins`), resolved through the address index the whole
  * build shares. The `folder:` Foundry-id spelling this function once read
  * beside it, and the per-pack `*-folders.yaml` that id was resolved against,

package/types/engine/homepage.d.mts

@@ -119,8 +119,8 @@ export function checkHomepageCount(found: ReadonlyArray<{
  * The one defaulted value on the page, and it defaults to the package's own
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
- * authored `title` wins, because a front page is allowed to greet a reader
- * differently from a package browser.
+ * authored `name.full` wins, because a front page may greet a reader
+ * differently from a package browser. A top-level `title` is also readable.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.

package/types/engine/note-format.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Format one addressed note's YAML without changing its Markdown body.
+ * Invalid YAML remains the YAML linter's finding.
+ *
+ * @param {string} markdown - The complete Markdown source.
+ * @returns {string} The source with canonical frontmatter.
+ */
+export function formatNoteFrontmatter(markdown: string): string;

package/types/engine/note-frontmatter.d.mts

@@ -0,0 +1,6 @@
+/** Return authored keys from an opening YAML frontmatter map. */
+export function authoredNoteKeys(markdown: any): string[];
+/** The complete ordered top-level vocabulary for addressed content notes. */
+export const NOTE_TOP_LEVEL_KEYS: readonly string[];
+/** Membership test for the top-level vocabulary. */
+export const NOTE_TOP_LEVEL_KEY_SET: Set<string>;

package/types/engine/system-block.d.mts

@@ -93,6 +93,17 @@ export function sharedProperty(fm: object, source: string, defaultValue?: any):
  * @returns {any} The value.
  */
 export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
+/**
+ * A system override followed by a shared `data:` value. The top-level value
+ * remains readable while content repositories move their authored fields.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm: object, block: string, key: string, defaultValue?: any): any;
 /**
  * The key a field is authored at **inside** a system block — step 2.
  *