@heroiclands/package-build 22.27.0 → 23.0.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @heroiclands/package-build
 
+## 23.0.0
+
+### Major Changes
+
+Every page a work of literature names in its subjects lists that work under **In song and story**, with its form beside the title, including works from a package this one depends on.
+
+### Patch Changes
+
+Affiliations, skills, attributes, mysteries, mystical abilities and miscellaneous gear without their own art show SoHL's default icons again instead of a broken image.
+
+Folder notes need only a nonempty body: a short line or placeholder no longer warns or fails, with or without `draft`. An empty folder body is still an error.
+
+Lore notes can be typed `literature` for epics, sagas, poems, legends and other works a people tells, sings or writes. A literature note may name its people, its form, its subjects and its language, and each appears in the note's infobox, with the people, subjects and language as links.
+
+## 22.28.0
+
+### Minor Changes
+
+Notes now require a nonempty body, including drafts, folders and homepages. Short written notes still warn unless tagged as drafts.
+
 ## 22.27.0
 
 ### Minor Changes

package/bin/content-commands.mjs

@@ -226,7 +226,12 @@ const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS, hm3: HM3_ITEM_FIELDS };
 /** Register the content operations on the package command line. */
 export function registerContentCommands(cli) {
     return cli
-        .command(withIndexPreflight(packageCommand(), (_config, argv) => argv.action === "compile"))
+        .command(
+            withIndexPreflight(
+                withBodyPreflight(packageCommand(), (_config, argv) => argv.action === "compile"),
+                (_config, argv) => argv.action === "compile",
+            ),
+        )
         .command(depsCommand())
         .command(docsCommand())
         .command(withIndexPreflight(lintCommand()))
@@ -235,11 +240,17 @@ export function registerContentCommands(cli) {
         .command(withIndexPreflight(linksCommand()))
         .command(formatCommand())
         .command(markdownCommand())
-        .command(contentIndexCommand())
-        .command(withIndexPreflight(siteCommand(), publishesContentPages))
+        .command(
+            withBodyPreflight(
+                contentIndexCommand(),
+                () => true,
+                (config, argv) => argv.root || config.paths.content,
+            ),
+        )
+        .command(withIndexPreflight(withBodyPreflight(siteCommand()), publishesContentPages))
         .command(
             withIndexPreflight(
-                pdfCommand(),
+                withBodyPreflight(pdfCommand(), (config) => Boolean(config.pdf)),
                 (config) => config.pdf && publishesContentPages(config),
             ),
         )
@@ -380,6 +391,43 @@ function proseCommand() {
     };
 }
 
+/** Refuse invalid note bodies before emitting metadata, packs, pages or a book. */
+function withBodyPreflight(
+    command,
+    shouldCheck = () => true,
+    contentRoot = (config) => config.paths.content,
+) {
+    const handler = command.handler;
+    return {
+        ...command,
+        handler: async (argv) => {
+            try {
+                const config = loadPackConfig();
+                if (shouldCheck(config, argv)) {
+                    const contentBase = contentRoot(config, argv);
+                    if (!fs.existsSync(contentBase)) return handler(argv);
+                    const records = indexRecordsFor({ config, contentBase });
+                    const { findings } = lintNoteStates(contentBase, {
+                        records,
+                        contentPackage: config.contentPackage,
+                    });
+                    const errors = findings.filter((finding) => finding.severity === "error");
+                    if (errors.length) {
+                        for (const finding of errors) emitDiagnostic(finding);
+                        process.exitCode = 1;
+                        return;
+                    }
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+                return;
+            }
+            return handler(argv);
+        },
+    };
+}
+
 /** Check declared dependency indexes before an index-consuming command does any work. */
 function withIndexPreflight(command, shouldCheck = () => true) {
     const handler = command.handler;
@@ -1167,7 +1215,7 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
 
-                // Whether every empty body is a stub on purpose, and how
+                // Whether every note has a body, and how
                 // finished the tree is. The counts and the oldest drafts are
                 // prose rather than findings: a note nobody has finished is not
                 // wrong, and 464 warnings a reader cannot clear is how a report

package/ci/publish-npm.mjs

@@ -0,0 +1,49 @@
+/*
+ * 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
+ */
+
+/**
+ * Publish this package to npm, with provenance wherever it can be generated.
+ *
+ * `publishConfig.provenance` is `true`, and npm refuses a publish with
+ * `Automatic provenance generation not supported for provider: null` anywhere
+ * that cannot mint a Sigstore identity. That is a CI runner holding an OIDC
+ * token: GitHub Actions with `id-token: write`, which exposes
+ * `ACTIONS_ID_TOKEN_REQUEST_URL`, or GitLab CI with `SIGSTORE_ID_TOKEN`.
+ * Everywhere else — a desk — this passes `--provenance=false`, so the publish
+ * goes ahead unattested rather than failing.
+ *
+ * Arguments after `--` reach `npm publish` unchanged, so
+ * `npm run deploy:npm -- --dry-run` shows the tarball without publishing it.
+ * `prepack` builds the declarations and the asset index on the way.
+ *
+ * Not a `package-build` subcommand: it publishes this package and no other.
+ */
+
+import { spawnSync } from "node:child_process";
+
+const env = process.env;
+const provenance =
+    (env.GITHUB_ACTIONS === "true" && Boolean(env.ACTIONS_ID_TOKEN_REQUEST_URL)) ||
+    (env.GITLAB_CI === "true" && Boolean(env.SIGSTORE_ID_TOKEN));
+
+if (!provenance) {
+    console.log("deploy:npm: no OIDC identity here; publishing without provenance.");
+}
+
+const args = ["publish", ...(provenance ? ["--provenance"] : ["--provenance=false"])];
+const result = spawnSync("npm", [...args, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+});
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);

package/docs/api.md

@@ -441,16 +441,16 @@ Drawing a declared infobox: HTML for separate Foundry pages appended after autho
 
 The three states of a note — **stub**, **draft**, **full** — and the one observable fact they rest on. A note whose body is empty is a stub: it carries its facts into the index and is queryable there, and it has no page, no address and no link target. Nothing is stored: the ladder is derived once in the SQL `entries` view and no note can assert its own state.
 
-| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                |
-| --------------------- | ------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                    |
-| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                   |
-| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` are structural and exempt                |
-| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                   |
-| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all |
-| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                             |
-| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
-| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words     |
+| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                                               |
+| --------------------- | ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                                                   |
+| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                                                  |
+| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` retain their addresses in this classification, but still require bodies |
+| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                                                  |
+| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all                                |
+| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                                                            |
+| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                                                   |
+| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words                                    |
 
 ### `engine.draftNotice`
 
@@ -471,7 +471,7 @@ What a draft note says about itself, in one sentence, on every surface it reache
 
 ### `engine.stubLint`
 
-An empty body must be deliberate. Four rules hold the state honest — a stub states what it is, a stub is not tagged `draft`, a body that renders to nothing is an abandoned draft, and a short unmarked body is asked whether it forgot its marker — and two reports say what the rules cannot decide.
+Every typed note must have a nonempty body. Empty and whitespace-only bodies are errors regardless of description or `draft` tag, including structural types such as `folder` and `homepage`. Placeholder-only bodies also produce errors. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. A `folder` note is held only to the nonempty rule: any body, placeholder or short, passes with or without `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing. The state classification helpers still describe incomplete records for inspection; their classifications do not exempt notes from validation.
 
 | Export             | Signature                                                  | Returns                                             | Use it when                                                                                   |
 | ------------------ | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |

package/docs/authoring/first-note.md

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

package/docs/content-format.md

@@ -9,6 +9,8 @@ subType: userguide
 
 A content package begins with Markdown notes under `assets/content/`. Each note has YAML frontmatter describing its identity and data, followed by prose. Folder names beneath `assets/content/` are for authors; `type`, `subType`, and Addresses determine what the build creates.
 
+Every typed note requires a nonempty body, including drafts, folders and homepages. An empty or whitespace-only body is an error. A nonempty body with fewer than 25 prose words warns unless tagged `draft`; the tag never exempts an empty body. A `folder` note needs only a nonempty body: any content passes, with or without `draft`.
+
 Start with [your first note](authoring/first-note.md). It explains the smallest valid note and shows the JournalEntry, web page, book entry, and content-index record made from it. Then use the chapters below in the order your note needs them.
 
 | Need                                                      | Read                                                        |

package/docs/guides/site.md

@@ -144,12 +144,12 @@ The build always writes `title`, `slug`, `url`, `kbfolder`, `package` and
 note. `infoboxes` is assembled from the note's own fields, so no note authors
 it and nothing in the note format accepts it.
 
-The build writes `resolvedDates`, `related`, `contains`, `governed_by`, `governed_places`
-and `map` only when it has something to write. A page with no links either way
+The build writes `resolvedDates`, `related`, `contains`, `governed_by`, `governed_places`,
+`works` and `map` only when it has something to write. A page with no links either way
 carries no `related`, and a place with no drawing carries no `map`.
 
-An authored `aliases`, `related`, `contains`, `governed_by`, `governed_places` or `map` is
-dropped. Each states a fact about the whole tree rather than about one note, so
+An authored `aliases`, `related`, `contains`, `governed_by`, `governed_places`, `works` or
+`map` is dropped. Each states a fact about the whole tree rather than about one note, so
 the build replaces whatever a note wrote.
 
 Artwork addresses are rewritten in place under `data`. A page's `data.icon`,

package/docs/reference/format-details.md

@@ -837,7 +837,7 @@ and the whole of it is the suffix.
 
 ```markdown
 ![A map of the Vale](images/maps/valeofthorns.webp) <!-- this package's -->
-![A shield](sohl/assets/icons/noun/shield.svg) <!-- the sohl package's -->
+![A shield](sohl/assets/icons/noun/shieldnn.svg) <!-- the sohl package's -->
 ```
 
 The four forms, for a `harnensemble` note (the `harnensemble` content package
@@ -850,14 +850,14 @@ ships as the Foundry module `harn-ensemble`) writing `images/map.webp`:
 | **Web**     | `https://cdn.heroiclands.org/harnensemble/images/map.webp` |
 | **Book**    | `assets/images/map.webp`, staged beside the Typst source   |
 
-And for the same note writing `sohl/assets/icons/noun/shield.svg`, a file the
+And for the same note writing `sohl/assets/icons/noun/shieldnn.svg`, a file the
 system ships and this repository does not hold:
 
 | Surface     | Address                                                       |
 | ----------- | ------------------------------------------------------------- |
-| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`                   |
-| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository      |
-| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`      |
+| **Foundry** | `systems/sohl/assets/icons/noun/shieldnn.svg`                 |
+| **Local**   | `assets/icons/noun/shieldnn.svg`, in the `sohl` repository    |
+| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shieldnn.svg`    |
 | **Book**    | not carried, unless a declared replacement carries it instead |
 
 **The content package name and Foundry id are separate values.**
@@ -2006,8 +2006,20 @@ convention rather than declared in a field — see
 
 ### Three states of a note
 
-A note has three states, and two of them are nothing but conventions the format
-already carried.
+Every typed note requires a nonempty body after its closing frontmatter fence.
+An empty or whitespace-only body is an error, regardless of description or
+`tags: [draft]`. This includes `folder` and `homepage` notes. Untyped vault
+scaffolding is excluded. A nonempty body with fewer than 25 prose words warns
+unless tagged `draft`; the tag never exempts an empty body. A `folder` note is
+held only to the nonempty rule: any body, a placeholder or a single line
+included, passes with or without `draft`.
+
+The `lint`, `content-index`, `package compile`, `site` and `pdf` commands enforce
+body errors. Write a short beginning and tag it `draft` when work is unfinished.
+
+The internal classification below describes records, including incomplete notes
+that inspection APIs can still read. A **stub** is invalid authored content and
+must receive a body before these commands can publish it.
 
 | State     | Body    | Marker          | Page         | Document                          | Link target |
 | --------- | ------- | --------------- | ------------ | --------------------------------- | ----------- |
@@ -2039,13 +2051,13 @@ same.
 
 | After the fence         | Empty? | What happens                                                    |
 | ----------------------- | ------ | --------------------------------------------------------------- |
-| Nothing, or blank lines | yes    | A stub                                                          |
+| Nothing, or blank lines | yes    | An error, with or without `draft`                               |
 | An HTML comment         | no     | A note with a body that renders to nothing. The lint reports it |
 | A horizontal rule       | no     | The same                                                        |
 | A lone heading          | no     | The same                                                        |
 | `_To be written._`      | no     | The same                                                        |
 
-An HTML comment is deliberately not empty. An invisible marker does not make a valid stub; use an empty body when the note has no prose.
+An HTML comment is deliberately not empty, but an invisible marker does not supply prose. Replace placeholder-only content with written text. A `folder` note is the exception: any of these bodies satisfies it, and the lint reports nothing.
 
 #### What a stub emits
 
@@ -2090,12 +2102,12 @@ What is suppressed with the page is the web address and the link target: a
 wikilink into a stub is refused, and a table cell listing one prints its name as
 plain text rather than as a link.
 
-#### Two types are structural and exempt
+#### Structural classification does not exempt validation
 
-`folder` and `homepage` have no body by design — a folder note's page is a
-generated section index, and the homepage's is the site's front door. An empty
-body on either keeps its address and resolves as **full**, because such a note is
-complete.
+A `folder` note's page is a generated section index, and the homepage is the
+site's front door. The classification helpers retain their addresses and report
+**full** even when their bodies are empty. Validation still rejects an empty
+body for both types.
 
 Every type in the vocabulary declares whether an empty body suppresses its page,
 so adding a type means answering the question rather than inheriting a default.
@@ -2784,6 +2796,15 @@ An Item can mark its readable description with `# ... {#description}`. That head
 
 Generates a living (or undead, or spirit) being.
 
+**subType**:
+
+- npc: A character meant to be encountered. It may describe a reusable template and need not be
+  a singular individual.
+- character: A detailed, playable, singular individual.
+- creature: Any being that is neither a character nor an NPC.
+
+See [a being's subtype describes the subject](#a-beings-subtype-describes-the-subject).
+
 | `data` property             | Values                                         | Description                                                                                                                                           |
 | --------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `tokenIcon`                 | `Address`                                      | What a token on the canvas wears — an `icon` address; defaults to `icon`                                                                              |
@@ -3916,22 +3937,39 @@ the setting itself, rather than instructions or other apparatus for the GM.
   which covers the _reckoning_ — a festival's date is calendar and the festival is not, and a
   tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
   of people rather than an occasion they attend.
-
-| `data` property         | Values                                                                        | Description                                                                         |
-| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `epoch`                 | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1                                |
-| `months`                | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year                                  |
-| `weekdays`              | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously                        |
-| `seasons`               | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                                          |
-| `namedDays`             | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                                            |
-| `eras`                  | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year                               |
-| `formats`               | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default                                  |
-| `events`                | `{ when, until?, recurs? }[]`                                                 | This note's dated occurrences, each with its own relationships and chronicle fields |
-| `events[].when`         | a date, or `"0.<day>"`                                                        | The occurrence's anchor and first instance — required                               |
-| `events[].until`        | a date                                                                        | Where the occurrence ran to, or where a recurring series stopped                    |
-| `events[].recurs`       | `{ every }` or `{ on }`                                                       | How further occurrences are found, absent for a one-time occurrence                 |
-| `events[].recurs.every` | whole number of years, 1 or more                                              | A period counted on the canonical axis from `when`                                  |
-| `events[].recurs.on`    | list of dates, strictly increasing, each later than `when`                    | Recorded occurrences beyond the first, in place of a period                         |
+- literature: A work a people composes and keeps — an epic, saga, poem, legend, hymn or
+  chronicle, told, sung or written. Held apart from `history`, which states what happened: a
+  legend is literature whether or not its events took place, and a chronicle is literature as a
+  work even where its events are also history.
+
+Each note a work names in `data.subjects` lists that work on its own site page, under **In
+song and story**, with the work's `form` beside its title; the subject note writes nothing.
+A work in a fetched index lists on this package's pages when that index carries its
+`subjects`.
+
+Calendar fields are written only on a `calendar` note, and `culture`, `form`, `subjects` and
+`language` only on a `literature` note; written on any other lore subType, each is an error at
+its own key.
+
+| `data` property         | Values                                                                        | Description                                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `epoch`                 | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1                                                              |
+| `months`                | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year                                                                |
+| `weekdays`              | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously                                                      |
+| `seasons`               | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                                                                        |
+| `namedDays`             | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                                                                          |
+| `eras`                  | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year                                                             |
+| `formats`               | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default                                                                |
+| `culture`               | `Address`                                                                     | `literature` only: the people whose work it is, naming a lore note with `subType: culture`                        |
+| `form`                  | `string`                                                                      | `literature` only: the kind of work in its people's own terms — `epic`, `saga`, `praise-song`, `elegy`. Free text |
+| `subjects`              | `Address[]`                                                                   | `literature` only: the beings, places, gods, events and other notes the work concerns                             |
+| `language`              | `Address`                                                                     | `literature` only: the tongue it is composed in, naming a skill note with `subType: language`                     |
+| `events`                | `{ when, until?, recurs? }[]`                                                 | This note's dated occurrences, each with its own relationships and chronicle fields                               |
+| `events[].when`         | a date, or `"0.<day>"`                                                        | The occurrence's anchor and first instance — required                                                             |
+| `events[].until`        | a date                                                                        | Where the occurrence ran to, or where a recurring series stopped                                                  |
+| `events[].recurs`       | `{ every }` or `{ on }`                                                       | How further occurrences are found, absent for a one-time occurrence                                               |
+| `events[].recurs.every` | whole number of years, 1 or more                                              | A period counted on the canonical axis from `when`                                                                |
+| `events[].recurs.on`    | list of dates, strictly increasing, each later than `when`                    | Recorded occurrences beyond the first, in place of a period                                                       |
 
 `data.events` is available on every `lore` subType. Each entry's `kind`, `depth`, `summary`, `sources`, `standing`, `accounts`, `who`, `where`, `unresolved`, `follows` and `names` hold its chronicle detail; their shapes belong to whatever design governs chronicle records, and this format only asks that they sit inside an entry. The shared format checks `when`, `until` and `recurs`; a content package can check the rest. `events` itself does not appear as an infobox row, but a recurring entry's computed next occurrence does.
 
@@ -4735,8 +4773,8 @@ the map for the pack it is writing and falls back to `default` when there is no
 such key, so a mistyped `journal:` files the folder wherever the default puts it
 — exactly the hierarchy the key was written to override, and silently.
 
-**A folder note carries no prose.** It is structure, not content, so it produces
-no documentation journal and takes no part in `docEntryTypes`.
+**A folder note requires a body**, like every typed note. Its body does not
+produce a documentation journal or take part in `docEntryTypes`.
 In a compiled Foundry journal, a wikilink to a folder prints its label as text:
 the folder can materialise in several packs and has no single compendium UUID.
 

package/docs/reference/note-types.md

@@ -417,7 +417,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 ### lore
 
-**Subtypes:** `cosmology`, `deity`, `theology`, `arcana`, `spirit`, `economy`, `law`, `calendar`, `history`, `material`, `folk`, `culture`, `custom`, `bestiary`, `gathering`.
+**Subtypes:** `cosmology`, `deity`, `theology`, `arcana`, `spirit`, `economy`, `law`, `calendar`, `history`, `material`, `folk`, `culture`, `custom`, `bestiary`, `gathering`, `literature`.
 
 Lore records in-world knowledge. A `culture` describes a people; a `custom` describes how they practice a rite, observance, or usage. A `material` describes a physical constituent and its qualities, which may vary by region. See the [lore subtype definitions](format-details.md#type-lore) for the complete vocabulary.
 
@@ -430,6 +430,10 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.namedDays` | list of `{ name, abbreviation?, day }`                                              | Names assigned to particular days of the year.                                                                                       |
 | `data.eras`      | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months.                                                 |
 | `data.formats`   | map of named Calendaria format strings                                              | Named patterns for reading and writing this calendar's dates.                                                                        |
+| `data.culture`   | an Address                                                                          | The people whose work this is, as a culture lore note.                                                                               |
+| `data.form`      | string                                                                              | The kind of work in its people's own terms — an epic, a saga, a praise-song, an elegy. Free text.                                    |
+| `data.subjects`  | list of Addresses                                                                   | The beings, places, gods, events and other notes the work concerns.                                                                  |
+| `data.language`  | an Address                                                                          | The tongue the work is composed in, as a language skill note.                                                                        |
 | `data.events`    | list of `{ when, until?, recurs? }`                                                 | This note's dated occurrences — a founding once, an anniversary that recurs, or a list of recorded happenings.                       |
 
 ### map

package/docs/reference/theme-pages.md

@@ -14,7 +14,7 @@ map, search, and the markup an image or a figure renders as — and names the
 classes a consumer styles against.
 
 **None of the sections below is an authoring instruction.** `infoboxes`,
-`related`, `contains`, `governed_by`, `governed_places`, `map`, `package`, `slug`, `url`
+`related`, `contains`, `governed_by`, `governed_places`, `works`, `map`, `package`, `slug`, `url`
 and `title` cannot be written by a note at all: a note's top-level region is
 closed and does not admit them, so each arrives already resolved by the time
 the theme sees it. Read this page when a panel is missing or a class needs
@@ -215,6 +215,37 @@ uses, so a region with forty settlements stays scannable.
 A page whose front matter declares none of `contains`, `governed_by` or
 `governed_places` renders no card at all.
 
+## The "In song and story" card
+
+`partials/literature-works.html` renders a second card directly below the
+government card, listing the works of literature that name the page's subject.
+The build derives `works` from every `literature` lore note's `data.subjects`,
+including works a fetched index carries, so no note writes it:
+
+```yaml
+---
+works: [{ title: …, url: …, form: … }] # works naming this page, sorted by title
+---
+```
+
+`form` is the work's `data.form`, printed in parentheses beside its title, and is
+absent when the work states none. A work naming one subject twice lists once, and
+a work naming itself is not listed on its own page. An entry's `url` is absent
+for a work that publishes no page, which renders as plain text through
+`partials/holdings/entry.html`. A page no work names carries no `works` and
+renders no card.
+
+The card reuses the government card's classes, so a consumer styling one styles
+both; `.literature-works` on the `<section>` tells them apart.
+
+| class                   | drawn as                          |
+| ----------------------- | --------------------------------- |
+| `.literature-works`     | the card, beside `.holdings`      |
+| `.holdings-table-label` | "In song and story"               |
+| `.holdings-table-grid`  | the grid of works                 |
+| `.holdings-entry-name`  | a work's title, linked or plain   |
+| `.holdings-entry-kind`  | the work's form, beside its title |
+
 ## The place map
 
 A place page with `map: from-<shortcode>.svg` displays a **From here** panel

package/engine/content-format.yaml

@@ -241,6 +241,10 @@ types:
             - namedDays
             - eras
             - formats
+            - culture
+            - form
+            - subjects
+            - language
             - events
         subTypes:
             - cosmology
@@ -258,6 +262,7 @@ types:
             - custom
             - bestiary
             - gathering
+            - literature
     map:
         data:
             - scene

package/engine/folder-notes.mjs

@@ -42,9 +42,8 @@
  * because a `Folder` is a core Foundry document like a `JournalEntry` or a
  * `Scene`, not a system's.
  *
- * **A folder note carries no prose.** It is structure, not content, so it wants
- * no documentation journal and takes no part in `docEntryTypes` — the one
- * open decision, settled the way it recommended.
+ * **A folder note requires a body** under author validation. That body creates
+ * no documentation journal and takes no part in `docEntryTypes`.
  *
  * @module
  */

package/engine/index.mjs

@@ -93,7 +93,7 @@ export * as noteState from "./note-state.mjs";
 /** What a draft note says about itself, in one sentence, on every surface. */
 export * as draftNotice from "./draft-notice.mjs";
 
-/** Whether every empty body is a stub on purpose, and how finished a tree is. */
+/** Require written bodies on typed notes and report how finished a tree is. */
 export * as stubLint from "./stub-lint.mjs";
 
 /** What a place is next to and reachable from: the closed sets, and the checks. */