@heroiclands/package-build 22.4.6 → 22.5.0

package/docs/configuration.md

@@ -770,6 +770,7 @@ Any other key under `docs.itemFields` is refused:
 | `site.notfound`    | object   | `null`                                      |
 | `site.hugo`        | object   | `{}`                                        |
 | `site.search`      | boolean  | `true`                                      |
+| `site.maps`        | boolean  | `true`                                      |
 
 How much of a package reaches the web at all is **not** here — it is
 [`publish.site`](#publish). `site` is framing: which named pass bundle
@@ -819,7 +820,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo, search).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo, search, maps).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -950,6 +951,24 @@ site:
 
 > ``package-build config: `site.search` must be a boolean.``
 
+`site.maps` is whether every place page carries the map from that place. On
+by default: `content-build site` draws the map `content-build map --from`
+draws — the place's borders and routes, each neighbour at its bearing — for
+every place that states a border or a route or is named in one, lays it beside
+the page as `from-<shortcode>.svg`, and names the file in the page's front
+matter as `map`, which the theme inlines so every place name on it is a link
+to that place's page. A place with no relation carries no map and no key.
+GraphViz draws; when it is not installed the build says so once, as a
+warning, and writes every page as it would without maps — a site never fails
+for want of one. `false` draws nothing and asks nothing of GraphViz.
+
+```yaml
+site:
+  maps: false
+```
+
+> ``package-build config: `site.maps` must be a boolean.``
+
 ### The generated Hugo configuration
 
 `content-build site` writes `build/hugo/hugo.toml` on every run. Every value

package/docs/content-format.md

@@ -1657,6 +1657,83 @@ not honoured in part either.
 convention rather than declared in a field — see
 [the lead image](#the-lead-image).
 
+### Three states of a note
+
+A note has three states, and two of them are nothing but conventions the format
+already carried.
+
+| State     | Body    | Marker          | Page        | Document                         | Link target |
+| --------- | ------- | --------------- | ----------- | -------------------------------- | ----------- |
+| **stub**  | empty   | none            | no          | yes, where its type compiles one | no          |
+| **draft** | written | `tags: [draft]` | yes, marked | yes                              | yes         |
+| **full**  | written | none            | yes         | yes                              | yes         |
+
+**Full is the absence of everything.** It is the default and carries no marker,
+which is right: the overwhelming majority of a finished corpus should say
+nothing about its own finishedness.
+
+There is no new frontmatter key, no new filetype and no second parser. A stub is
+a `.md` file the walk already finds, and the moment somebody writes a body it
+becomes an ordinary note — nothing moves, nothing is deleted, and every inbound
+link starts resolving.
+
+#### A stub is a note with an empty body
+
+> **The body is empty when everything after the closing frontmatter fence is
+> whitespace.** Nothing else is empty.
+
+The rule is that severe because the test has to be one you can apply by looking
+at the file. Every softer rule makes two files that look different behave the
+same.
+
+| After the fence         | Empty? | What happens                                                    |
+| ----------------------- | ------ | --------------------------------------------------------------- |
+| Nothing, or blank lines | yes    | A stub                                                          |
+| 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 deciding whether
+a page exists is exactly the failure the retired `draft:` field was removed for.
+
+#### What a stub emits
+
+A stub's index record is its frontmatter plus the derived keys, **minus
+`address` and `anchors`**. The absent address is the whole signal, and it is the
+column a table renderer already reads.
+
+It keeps everything else:
+
+- **`file`**, which is what you edit and what every diagnostic names.
+- **`id` and `foundry`**, because a **document is derived from `data:`, not from
+  prose**. An unwritten arcane talent still compiles into its Item, and its
+  documentation journal is still a document in its own right. **The empty body
+  suppresses the page, never the document.**
+
+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
+
+`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.
+
+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.
+
+#### A stub is still referenceable as data
+
+`borders.to` and `routes.to` name a place by shortcode, and those are **index
+relations rather than page links**: a border with a stub on the far side is a
+valid statement about the world and resolves. So does `parents` for the
+containment tree and `domains` for tenure — a stub appears in its region's
+`contains` and on its holder's `holdings`, rendered as plain text. What a stub
+cannot be is the target of a wikilink, because a wikilink points at a page.
+
 ### What a note produces
 
 Note types fall into two groups, and only the first has a mapping table.
@@ -1903,6 +1980,49 @@ journals. A nested field is addressed exactly as a note authors it —
 every nested object is inferred as a struct. A field a note type does not carry
 reads `NULL` rather than failing.
 
+**`notes` leaves out stubs; `entries` does not.** Both carry a derived `state`
+column — `stub`, `draft` or `full` — and `notes` is exactly
+`SELECT * FROM entries WHERE state <> 'stub'`. So every table already written
+selects what it always selected, and gains `state` for free; a table that should
+list the unwritten beside the written changes one word:
+
+````markdown
+```sql
+SELECT address.slug    AS _ref,
+       name.full       AS "Name",
+       state           AS "State",
+       m.name          AS "Market",
+       data.population AS "People"
+FROM entries
+LEFT JOIN market m ON m.value = data.market
+WHERE type = 'place' AND subType = 'settlement'
+  AND list_contains(data.parents, 'place-aelwyth')
+ORDER BY data.population DESC NULLS LAST, name.full COLLATE NOCASE
+```
+````
+
+A written settlement renders as a link and a stub renders as plain text, from
+one query with no branch in it: `_ref` is the stub's absent address, and the
+renderer already prints a bare cell where it is null.
+
+A fence selecting `FROM notes` that **would** gain rows from `FROM entries` is
+warned about at the fence, with the count — so adopting stubs in a given table
+stays a decision somebody makes rather than one they forget.
+
+The ladder is what makes "how finished is this?" a query:
+
+```sql
+SELECT state, count(*) AS n FROM entries GROUP BY state ORDER BY state
+```
+
+**`market`** is the six-step market scale as a relation — `value`, `name`,
+`trade` — so a table prints `village` beside the number a note wrote without a
+second copy of the scale living in authored content.
+
+**The state is derived, never stored.** No index record carries it, no note can
+author it, and nothing in `data:` may claim it: the only authored signal is the
+`draft` tag, which marks the one thing reading the body cannot reveal.
+
 **Two aliases are read by the renderer rather than printed**, because which
 column links and where a section breaks are decisions about output, not
 relational operations:
@@ -2440,6 +2560,23 @@ subType `deity` covers a god's nature, domains, epithets and aspects in prose.
 That frees the name for the territorial sense, which earns it: every affiliation
 subType holds sway somewhere, while the divine sense applies to one.
 
+**`domains` names what the affiliation holds directly**, and nothing beneath
+it. A polity whose `domains` names a region holds the region; the settlements
+within it are the region's, reached through its `contains`, and are not
+repeated here. A house holds its manors and names each; the crown holds the
+realm and names the realm. What lies below a holder is answered by the two
+hierarchies together — `place.parents` for where a place sits, and
+`affiliation.parents` for whom a holder answers to — so a subinfeudated manor
+sits in one region by the first and under a lord of another polity by the
+second, and both pages say so.
+
+The website reads `domains` across the package and every fetched index and
+writes the affiliation's page a `holdings` list — every place its `domains`
+names, each entry `{ title, url, type, subType }`, sorted by `subType` then
+`title`, and absent when `domains` names nothing. Every place it names carries
+the affiliation back in `held_by`. Both are derived; a note that writes one has
+it replaced.
+
 If `sohl` is present, this becomes an `affiliation` item.
 
 | shared source    | → sohl             | → hm3 |
@@ -3087,9 +3224,38 @@ three maps, and none of those maps needs to know it is a keep.
 | `lore`          | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
 | `parents`       | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
 | `population`    | `number`                                            | Approximate population (precision 2 significant digits)                      |
+| `market`        | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
 | `borders`       | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
 | `routes`        | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
 
+#### What a settlement's market supports
+
+`population` states how many people a settlement holds; `market` states what a
+traveller can buy there. Those are different questions — two settlements of
+eight hundred are a different proposition when one holds a weekly market and
+the other a chartered fair with a moneylender — so a note states both, either,
+or neither.
+
+The value is a **class**, not a measurement. The numbers order six steps and do
+nothing else: a `5` is not a market two fifths larger than a `3`, it is a city
+rather than a town. `content-build lint` refuses a value off the scale instead
+of rounding it onto one, so a reader can trust that a number means the same
+thing on every page.
+
+| `market` value | the settlement is | what can be had there                                                                             |
+| -------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
+| `1`            | a hamlet          | no market — what neighbours trade among themselves                                                |
+| `2`            | a village         | a weekly market: staples, a smith, what a household cannot make                                   |
+| `3`            | a town            | a regular market, most common goods, several trades working full time                             |
+| `4`            | a market town     | a chartered fair, goods carried from a week away, a moneylender                                   |
+| `5`            | a city            | anything ordinary, in quantity; foreign goods; a guild structure                                  |
+| `6`            | a great city      | the rare and the imported as a matter of course; banking; the market from which other markets buy |
+
+The key is meaningful on a settlement, and the lint checks no `subType`
+condition — as it checks none for `population`. Which places a fact says
+something about is the author's judgement, and the `data:` container is closed
+per type rather than per subType.
+
 #### Where a place is, in relation to other places
 
 `parents` states what a place is **within**. Two more properties state what
@@ -3187,6 +3353,78 @@ closed set, and each finding is located at the entry that states it.
 | `river`         | boat               |
 | `lake`          | boat               |
 
+#### What lies within a place, and who holds it
+
+`parents` states what a place is within; an affiliation's `domains` states
+what it holds. The website reads both across the package and every fetched
+index and writes each place's page two lists, each entry
+`{ title, url, type, subType }` and each absent when empty:
+
+- `contains` — every place whose `parents` names this one, sorted by
+  `subType` then `title`. A region lists its settlements, sites, structures
+  and features; a settlement lists the structures within it.
+- `held_by` — every affiliation whose `domains` names this one, sorted by
+  `title`.
+
+Both are derived; a note that writes one has it replaced. **`domains` is
+never expanded**: a region held by a polity lists the polity in `held_by`, and
+a settlement within that region lists only the house or order whose `domains`
+names it — its lord's lord is reached through `affiliation.parents`.
+
+**A settlement, a site or a structure is held by someone.** One of those that
+no affiliation's `domains` names — in this package or in a fetched index — is
+a warning from `content-build lint`, `unheld land`, located at the note's
+`type:` line, so a gap in tenure shows while a note is written. A `world`, a
+`region` and a `feature` are exempt: a region is held through its polity's
+`domains`, and a river by nobody.
+
+#### Population figures
+
+`population` is an approximate count, written to two significant digits. A
+place states one, and so does an affiliation — how many people it counts,
+wherever they are. `content-build lint` reads those figures against each other
+and reports four warnings, each named by the phrase its message begins with.
+
+- **`over-held land`** — the polities whose `domains` name a place count more
+  people than the place states. A polity subordinate to another polity holding
+  the same place is already inside that polity's figure and is not counted
+  twice. A **settlement is exempt**: the polity of a city-state holds the city
+  and counts the hinterland around it, so its figure is properly the larger.
+- **`over-full region`** — the regions whose `parents` name a place count more
+  people than the place states. A region naming both its parent and its
+  grandparent counts under the nearer of the two, so a place written into two
+  levels of the hierarchy is not counted at both.
+- **`oversized settlement`** — a settlement states more people than a place
+  containing it does, whether its own region or any place above that.
+- **`disputed figure`** — a `doc` note carries a figure beside a wikilink to
+  the place or affiliation it belongs to, and the two disagree. The finding is
+  located at the number the page wrote, and a figure written twice is located
+  twice.
+
+The first three are reported on the note's own `data.population`; the fourth
+on the citation.
+
+**A figure is read as a population only where it carries `~`.** That marker is
+what separates a population from the other numbers a table puts beside a place
+— a distance, a stage count, a tally of days — so `| [[place-rgn\|X]] | ~2,000 |`
+is a claim about people and `| [[place-rgn\|X]] | 3 |` is not.
+
+**Rounding is admitted.** Two significant digits carry a half-unit of error,
+widest at the bottom of a decade, so a place whose figure falls up to five per
+cent below what it contains is not a finding.
+
+**An unstated figure is silent.** A place or affiliation with no `population`
+contributes nothing to a sum and is never the subject of a finding, so a
+half-written region is quiet rather than noisy. A fetched index carries
+`parents` and `domains` but no figure, so a dependency's places sit in the
+geography and its people are counted nowhere.
+
+**There is deliberately no urban-share rule.** The share of a region's people
+living in its named settlements cannot be measured from the notes: the
+settlement layer names the notable places and is complete nowhere, so the ratio
+reports how much of a region has been written rather than how much of it is
+urban.
+
 **A place declares only what is true of ground.** Four properties were removed
 because they were true of something else, and each removal has a home to go to.
 

package/docs/diagnostics.md

@@ -163,6 +163,50 @@ A configuration finding reads the same as any other:
 package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner, description, listType, listSubType).
 ```
 
+## A worked case: the three states of a note
+
+A note with an empty body is a **stub**, and the diagnostics about one show each
+rule above in turn.
+
+An empty body must be deliberate, so a stub that says nothing about itself is an
+error, located at its `type:` line — the key whose value made the note what it
+is:
+
+```text
+Regions/Aelwyth/Weyshott.md:4:1: error: this note has no body, so it is a stub — and a stub carries a `description`, which is the only sentence a reader gets and what every table listing it prints
+```
+
+A body that reduces to a placeholder is located **by searching the file for the
+phrase the rule matched**, which is the implicit-position rule: the finding is
+about a literal, so it lands on that literal rather than on the frontmatter:
+
+```text
+Regions/Aelwyth/Harad.md:14:1: error: this note's body says only "_To be written._", so it publishes a page that tells a reader nothing — empty the body to make this a stub, or write it
+```
+
+A link into a stub is refused, and because the stub is in the index the message
+can name the file to open rather than reporting that the address resolves
+nowhere:
+
+```text
+Regions/Aelwyth/Aelwyth_Region.md:41:14: error: address [[place-weyshott]] names a stub at Regions/Aelwyth/Weyshott.md, which has no body and therefore no page — name it in prose, or write the note
+```
+
+A body that may be a draft that forgot its marker is a **warning**, because the
+rule is a guess and a corpus holds many short notes that are complete:
+
+```text
+Rituals/Meivor.md:3:1: warning: this note's body is 4 word(s) and carries no `draft` tag — tag it if it is a beginning, and leave it alone if it says everything it has to say
+```
+
+And the counts, and the drafts nothing has touched in longest, are **prose**:
+a note nobody has finished is not wrong, so it is listed rather than flagged,
+and the summary carries no position because it has none.
+
+```text
+thalorna: 2572 notes — 2089 full, 464 draft, 19 stub.
+```
+
 ## Summary counts and prose are not findings
 
 A run's progress and summary lines — `42 address(es) across 10 note(s).`,

package/engine/content-index.mjs

@@ -114,6 +114,9 @@ import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
 export { collectAnchors };
 import { entriesForNote, foundryIdentities } from "./foundry-entries.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
+// The one statement of what an empty body means, shared with the lint and the
+// SQL view that derives the ladder from the absence this writes.
+import { isStubNote } from "./note-state.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 // The retired-field refusal and the key locator, so a note authoring a derived
 // key is reported where it is rather than as a bare abort.
@@ -128,16 +131,19 @@ import {
     DERIVED_KEYS,
     isAssetRecord,
     isNoteRecord,
+    isStub,
     noteFile,
     recordPath,
     sortKeysDeep,
 } from "./index-records.mjs";
+import { isDraftNote } from "./note-vocabulary.mjs";
 
 export {
     authoredFrontmatter,
     DERIVED_KEYS,
     isAssetRecord,
     isNoteRecord,
+    isStub,
     noteFile,
     recordPath,
     sortKeysDeep,
@@ -407,11 +413,18 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  * @param {string} [options.absPath] - The file, read only on the failing path to
  *   locate the offending key.
  * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {string} [options.body] - The note's markdown body, for its anchors
+ *   and for the one question that decides whether the note publishes a page. A
+ *   caller that states no body is stating an empty one, and the note is a stub.
  * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
  * @param {object} [options.manifest] - The package manifest, which the Foundry
  *   entries are derived against.
- * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @returns {Record<string, any>} The record, keys sorted at every depth. A
+ *   **stub** — a note with an empty body, on a type an empty body suppresses —
+ *   carries `address` and `anchors` as `null`: it publishes no page, so it
+ *   holds no address and offers no anchor. It keeps everything else, its `id`
+ *   and its `foundry` block included, because the document it compiles is
+ *   derived from `data:` rather than from prose.
  * @throws {Error} When the note carries a key this module derives, which would
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
@@ -430,23 +443,36 @@ export function buildIndexRecord({
     const posix = relPath.split(path.sep).join("/");
     const folder = posix.includes("/") ? posix.slice(0, posix.lastIndexOf("/")) : "";
     const address = noteAddress(frontmatter, contentPackage);
+    // Derived from the address the note *would* hold, because a stub keeps its
+    // Foundry document: a document is derived from `data:`, not from prose, and
+    // the empty body suppresses the page rather than the document.
     const entries = foundryEntries({ frontmatter, address, body, manifest });
+    // A stub — an empty body on a type an empty body suppresses — publishes no
+    // page, so it holds no address and offers no anchor to link to. **The
+    // absent address is the signal**, and it is the column the table renderer
+    // already reads through `_ref`. Everything else the note declares is kept:
+    // its file is what the author edits and what every diagnostic names, and
+    // its `id` and `foundry` block are the document it still compiles.
+    const stub = isStubNote(frontmatter, body);
 
     return /** @type {Record<string, any>} */ (
         sortKeysDeep({
             ...frontmatter,
             package: contentPackage,
-            address,
+            address: stub ? null : address,
             nameAscii: asciiName(frontmatter?.name?.full),
             aliasesAscii: asciiAliases(frontmatter?.name?.aliases),
             // Each anchor carries the link that reaches it, so a section is
             // addressable from the index without anyone re-deriving how an
             // anchor is spelled — and its file line, so an editor can jump
             // there rather than search for the heading.
-            anchors: collectAnchors(body, bodyLine).map((a) => ({
-                ...a,
-                link: address ? `${address.slug}#${a.slug}` : null,
-            })),
+            anchors:
+                stub ? null : (
+                    collectAnchors(body, bodyLine).map((a) => ({
+                        ...a,
+                        link: address ? `${address.slug}#${a.slug}` : null,
+                    }))
+                ),
             foundry: foundryBlock(
                 entries?.own,
                 systemOf(frontmatter?.type, KNOWN_DOCUMENT_SUBTYPE_MAPS),
@@ -609,22 +635,21 @@ export function collectContentIndex(
         }
         records.push(record);
 
-        // An item note is two documents, so it is two records.
-        const doc = foundryEntries({
-            frontmatter: fm,
-            address: record.address,
-            body,
-            manifest,
-        })?.doc;
-        if (doc?.key && record.address) {
+        // An item note is two documents, so it is two records. Derived from
+        // the address the note *would* hold rather than from the one its
+        // record carries: a stub withholds its own address and still compiles
+        // both documents, and the journal is one of them.
+        const address = noteAddress(fm, contentPackage);
+        const doc = foundryEntries({ frontmatter: fm, address, body, manifest })?.doc;
+        if (doc?.key && address) {
             records.push(
                 buildDocRecord({
                     frontmatter: fm,
-                    address: record.address,
+                    address,
                     entry: doc,
                     file: record.file,
                     contentPackage,
-                    anchors: record.anchors,
+                    anchors: record.anchors ?? [],
                 }),
             );
         }
@@ -751,8 +776,11 @@ export function indexRecordsFor({
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
  * @returns {{file: string, notes: number, assets: number, records: number,
- *   bytes: number}} Where it was written, how many notes and how many assets it
- *   holds, how many records that is in all, and its size.
+ *   bytes: number, full: number, draft: number, stub: number}} Where it was
+ *   written, how many notes and how many assets it holds, how many records that
+ *   is in all, its size, and the ladder those notes sit on — so the ratio of
+ *   written to unwritten is visible on every build rather than discovered in a
+ *   year.
  * @throws {Error} When the content tree is absent, or when it yields no note at
  *   all — an empty index is indistinguishable from a mis-pointed tree, and a
  *   reader would take it as the authoritative statement that this package has
@@ -794,7 +822,21 @@ export function emitContentIndex({ contentBase, outDir, config } = {}) {
     // note yields a second record for its documentation journal and a file
     // yields an asset record, so reporting records as notes would overstate how
     // large the tree is.
-    const notes = records.filter(isNoteRecord).length;
+    const noteRecords = records.filter(isNoteRecord);
     const assets = records.filter(isAssetRecord).length;
-    return { file, notes, assets, records: records.length, bytes: Buffer.byteLength(text) };
+    // Read off the records rather than from a second pass over the tree: a stub
+    // is the note whose address the emitter just withheld, and a draft is the
+    // tag the note carries, so both are already in hand.
+    const stub = noteRecords.filter(isStub).length;
+    const draft = noteRecords.filter((record) => !isStub(record) && isDraftNote(record)).length;
+    return {
+        file,
+        notes: noteRecords.length,
+        assets,
+        records: records.length,
+        bytes: Buffer.byteLength(text),
+        full: noteRecords.length - stub - draft,
+        draft,
+        stub,
+    };
 }

package/engine/content-links.mjs

@@ -182,6 +182,21 @@ export function buildLinkIndex(
         records ?? indexRecordsFor({ contentBase, config: resolved, skipDirectories, problems });
 
     const byKey = new Map();
+    /**
+     * Canonical address to the **stub** that would hold it.
+     *
+     * A stub has no page, so nothing may link to one — but it is a note the
+     * tree holds, and keeping it here is what lets the checker say so. The
+     * diagnostic names the note and reports that it has no body, where a link
+     * resolving against nothing at all can only say "resolves to no note".
+     *
+     * Kept beside {@link byKey} rather than in it, because the two answer
+     * different questions: `byKey` is what a **page** link may reach, and a
+     * stub is reachable only as **data** — a border's far side, a reference
+     * naming an item to stand beside. That is the whole boundary, and it is
+     * drawn here rather than per field.
+     */
+    const byStub = new Map();
     /** Canonical address to asset record, for the files this package ships. */
     const byAssetKey = new Map();
     const anchors = new Map();
@@ -234,12 +249,15 @@ export function buildLinkIndex(
             const canonical =
                 record.address?.canonical ??
                 canonicalKey(pkg, systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS), type, fm.shortcode);
-            byKey.set(canonical, note);
+            // A note with no address publishes no page, so its identity is
+            // filed where a link cannot reach it and a reference still can.
+            const into = record.address ? byKey : byStub;
+            into.set(canonical, note);
             if (hasDocEntry(type)) {
                 // A documentation journal is `none`: no game system defines a
                 // JournalEntry, and one note has one of them however many
                 // system blocks it carries.
-                byKey.set(canonicalKey(pkg, NO_SYSTEM, `doc${type}`, fm.shortcode), note);
+                into.set(canonicalKey(pkg, NO_SYSTEM, `doc${type}`, fm.shortcode), note);
             }
         }
     }
@@ -486,6 +504,26 @@ export function buildLinkIndex(
         return byKey.get(canonical) ?? byAssetKey.get(canonical);
     }
 
+    /**
+     * The **stub** an address names, or `undefined`.
+     *
+     * Asked only after {@link resolveAddress} has answered nothing, and read
+     * exactly as it reads: same qualifier, same defaults, same expansion. What
+     * it buys is the diagnostic — a link into a stub is refused because there
+     * is no page to reach, and the message can name the file the author has to
+     * open rather than saying the address resolves nowhere.
+     *
+     * @param {string} target - The link target, anchor already removed.
+     * @param {string} [keyPath] - The dotted frontmatter key path the link sits
+     *   under; body prose has none.
+     * @returns {object|undefined} The stub it addresses.
+     */
+    function stubAt(target, keyPath) {
+        const qualified = readQualifier(target, types, packages, noIndexPackages);
+        if (!qualified || qualified.reason) return undefined;
+        return byStub.get(expandAddress(qualified, { package: pkg, system: blockSystem(keyPath) }));
+    }
+
     /**
      * Every foreign manifest entry an address names, in package order.
      *
@@ -558,7 +596,12 @@ export function buildLinkIndex(
     function referenceHit(target) {
         const q = readQualifier(target, types, packages, noIndexPackages);
         if (!q || q.reason) return null;
-        const local = matchAddress([...byKey, ...byAssetKey], q);
+        // Stubs last, and deliberately included: a reference names an item to
+        // stand beside rather than a document to point at, so a border with a
+        // stub on the far side is a valid statement about the world. Resolving
+        // these against the addressed rows alone would report every one of
+        // them dead.
+        const local = matchAddress([...byKey, ...byAssetKey, ...byStub], q);
         if (local.length) return local[0][1];
         const abroad = matchAddress([...foreign.index], q);
         return abroad.length ? abroad[0][1] : null;
@@ -599,6 +642,8 @@ export function buildLinkIndex(
          */
         resolve: resolveAddress,
         resolveAddress,
+        /** The stub an address names, for the refusal that says which file. */
+        stubAt,
         manifestHit,
         foreignHits,
         referenceHit,
@@ -893,9 +938,9 @@ export function auditHomepageLinks(index) {
  *   which addresses a foreign manifest answered. Each `deadAddresses` entry
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
- *   `packages`), `"no-content-index"`, or `"unresolved"` — and every one of
- *   them is an **error**: the three resolvers agree on severity for every
- *   class.
+ *   `packages`), `"no-content-index"`, `"stub"` (with the stub's path) or
+ *   `"unresolved"` — and every one of them is an **error**: the three
+ *   resolvers agree on severity for every class.
  */
 export function auditLinks(index) {
     const { notes, anchors, linksOf, embedsOf, resolve, manifestHit, isAddress } = index;
@@ -957,6 +1002,15 @@ export function auditLinks(index) {
                 continue;
             }
             if (index.resolveAddress(target)) continue;
+            // A stub is in the index, so the refusal can name it. Asked before
+            // the foreign manifests, because a local note is what the author
+            // meant and reporting it as an unresolved foreign address would
+            // send them looking in the wrong package.
+            const stub = index.stubAt?.(target);
+            if (stub) {
+                deadAddresses.push({ ...at, reason: "stub", stub: stub.rel });
+                continue;
+            }
             // A manifest answers with the target package's own build output
             // rather than a reviewed guess.
             const hits = index.foreignHits(target);