@heroiclands/package-build 22.4.6 → 22.5.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @heroiclands/package-build
 
+## 22.5.0
+
+### Minor Changes
+
+**Three states of a note** — a note with no body is now a **stub**: it carries
+
+- A page's settlements, deities or characters can be listed with the unwritten
+  ones beside the written, and counted by how finished they are — select
+  `FROM entries` rather than `FROM notes`, which leaves stubs out as it always
+  has.
+- A folder note and the homepage are complete with no body, and keep their pages.
+- An unwritten note still compiles the compendium document its facts describe.
+- `content-build lint` asks a stub for a description, refuses one tagged
+  `draft`, and reports a body that says only "TBD".
+- Every build now prints how many of a package's notes are full, draft and stub.
+
+### Patch Changes
+
+**Population figures are checked against each other.** A region whose polities
+or inner regions count more people than it states, a settlement larger than the
+land around it, and a reference page carrying a figure the place's own note
+contradicts are each reported while the note is open.
+
+## 22.4.7
+
+### Patch Changes
+
+Every place page that states a border or a route, or is named in one, carries the map from that place: `from-<shortcode>.svg` beside the page and `map:` naming it in the front matter, with every place name on it a link to that place's page. GraphViz draws it; when GraphViz is not installed the site build says so once and writes every page without a map, and `site.maps: false` draws none.
+
+A place's page carries what lies within it and who holds it, and an affiliation's page carries what it holds, read from the `parents` and `domains` the notes already state — a dependency's places and affiliations included. `content-build lint` warns of unheld land: a settlement, site or structure that no affiliation's `domains` names.
+
+A `place` note can state a settlement's market class: `data.market`, a whole number from 1 to 6 beside `population`. `1` is a hamlet, with no market beyond what neighbours trade among themselves; `2` a village and its weekly market; `3` a town with several trades working full time; `4` a market town, its chartered fair and its moneylender; `5` a city, where anything ordinary can be had in quantity; `6` a great city that banks, imports as a matter of course, and is the market from which the other markets buy. The key is optional, and a value off the scale is reported at the line that states it rather than rounded onto a class nobody wrote.
+
 ## 22.4.6
 
 ### Patch Changes

package/CONTENT.md

@@ -1093,6 +1093,60 @@ it was addressed by the package rather than by a slug. It carries an address
 like every other note now; the guard is unchanged, because what it reads
 was never the key count.)
 
+### An empty body is a stub, on purpose
+
+A note whose body is empty is a **stub**: it carries its frontmatter into the
+content index and is queryable there, it keeps its `id` and the Foundry document
+its type compiles, and it publishes no page, no address and no link target. A
+note with a body and the `draft` tag is a **draft**, and one with a body and no
+tag is **full**. `docs/content-format.md` states the rule; this is what the lint
+does with it.
+
+Four findings and two reports:
+
+- **A stub carries a `description`.** With nothing in the body it is the only
+  sentence a reader gets, and it is what every table listing the note prints. An
+  **error**, at the note's `type:` line.
+- **A stub is not tagged `draft`.** A thing not started is not a thing in
+  progress. An **error**: remove the tag, or write a body.
+- **A body that reduces to nothing is an abandoned draft, not a stub.** A body
+  that is only headings, rules, comments and placeholder phrases — `TBD`, `To be
+written`, `Coming soon`, `Placeholder`, `N/A` — publishes a page that tells a
+  reader nothing. An **error** naming the phrase and where it sits: empty the
+  body to make it a stub, or write it.
+- **A short unmarked body may be a draft that forgot its marker.** Under
+  twenty-five words with no `draft` tag is a **warning, never an error**. A note
+  reading `See [[affiliation-meivor|Mëivōr]]` says everything it has to say, and
+  a corpus holds many of them.
+
+And two things the rules cannot decide, so they are reported as prose rather
+than flagged:
+
+- **The oldest drafts are listed** by last modification. A long-standing draft
+  is unfinished, which the tag already says; a warning nobody can clear is how a
+  report teaches its reader to stop looking at it.
+- **The counts are reported**, per package and per type:
+
+  ```text
+  thalorna: 2572 notes — 2089 full, 464 draft, 19 stub
+  ```
+
+  `content-build content-index` prints the same line, so the ratio of written to
+  unwritten is visible on every build rather than discovered in a year.
+
+#### Adopting it
+
+A package with no empty-bodied note is unaffected. A package that has them:
+
+1. Take the release and run `content-build lint`. Act on the stub findings — a
+   `description` on every stub, and no stub tagged `draft`.
+2. Change the `sql` fences that **should** see stubs from `FROM notes` to
+   `FROM entries`. The ones that would gain rows are warned about at the fence,
+   so the list comes to you.
+3. Read the site's page count. A stub publishes no page, so a tree with stubs
+   publishes fewer pages than it did — which is the point, and worth confirming
+   against any `min-pages` gate the deploy declares.
+
 ### Exactly one homepage
 
 A content tree declares **exactly one** `type: homepage` note. Zero is an
@@ -1183,6 +1237,45 @@ parent or child, or a pair listed twice by one mode. Each finding lands on the
 entry that states it. The keys, the sets and the days scale are specified under
 `type: place` in `docs/content-format.md`.
 
+**A settlement is held by someone.** An affiliation's `domains` names the
+places it holds, and a `place` of subType `settlement`, `site` or `structure`
+that no affiliation's `domains` names — in this tree or in a fetched index —
+is a warning, `unheld land`, at the note's `type:` line, so a gap in tenure
+shows. A region is held through its polity's `domains` and a feature by
+nobody, so neither is checked.
+
+**Population figures agree from the region down.** A place states
+`data.population` and an affiliation states how many people it counts, and four
+warnings read those figures against each other. The polities whose `domains`
+name a place must not count more people than the place states — `over-held
+land` — with a polity subordinate to another holding the same place counted
+once and a settlement exempt, its holder's figure counting a hinterland the
+settlement does not. The regions whose `parents` name a place must not count
+more than it states either — `over-full region` — a region naming both its
+parent and its grandparent counting under the nearer. A settlement must not
+hold more than any place containing it states, which is `oversized settlement`.
+And a `doc` note carrying a figure beside a wikilink to the place or
+affiliation it belongs to must state that note's figure, which is `disputed
+figure`, located at the number it wrote. Figures are authored to two
+significant digits, so a parent rounded up to five per cent below what it
+contains is not a finding, and a place or affiliation stating no figure is
+neither compared nor counted. A fetched index carries no figure, so a
+dependency's people are counted nowhere. There is deliberately **no urban-share
+rule**: a share computed from the named settlements against a region's total
+measures how much of the region has been written, not how much of it is urban.
+
+**A settlement's market class is one of six.** `data.market` states what trade
+a settlement supports — `1` a hamlet, with no market beyond what neighbours
+trade among themselves; `2` a village and its weekly market; `3` a town with
+several trades working full time; `4` a market town, its chartered fair and its
+moneylender; `5` a city, where anything ordinary can be had in quantity; `6` a
+great city that banks, imports as a matter of course, and is the market from
+which the other markets buy. The numbers order the steps and do nothing else, so a value off the
+scale is an error at the value that states it rather than a number rounded onto
+a class the author did not write. The key is optional and the lint checks no
+`subType` condition, as it checks none for `population`. The scale is stated
+under `type: place` in `docs/content-format.md`.
+
 Nothing here writes. A check reports and an author fixes.
 
 **`content-build map` draws what those keys state.** `--tree` is the author's
@@ -2035,7 +2128,15 @@ the build fails naming both.
 ### Every note's address, and every anchor it defines
 
 A record states the address a wikilink writes to reach the note, and every
-`{#slug}` anchor its body declares:
+`{#slug}` anchor its body declares — unless the note is a **stub**, which
+carries both as `null`: it publishes no page, so it holds no address and offers
+no anchor to reach. Everything else it declares is kept, its `id` and `foundry`
+block included, because a document is derived from `data:` rather than from
+prose.
+
+The SQL views read that absence as the state: `entries` is every row plus a
+derived `state` column, and `notes` is `entries` without the stubs. Nothing
+about the state is stored, and no note may author it.
 
 ```json
 {
@@ -2409,6 +2510,96 @@ The theme's `related.html` partial reads both lists and renders them as one
 `related` is derived, never authored: what links to a page is a fact about
 every other page in the tree. A note that writes one has it replaced.
 
+### A place page says what lies within it and who holds it; an affiliation page says what it holds
+
+Two keys the notes already carry answer three questions a reader asks of a
+page. A place's `data.parents` is geography — what it sits within — and an
+affiliation's `data.domains` is tenure — what it holds. The build reads both
+across the tree and every fetched index, inverts them, and writes each page
+the lists that concern it, shaped like `related`:
+
+```yaml
+# on a place
+contains: # every place whose `parents` names this one
+  - title: Khaset-Mehtet
+    url: /thalorna/place-khasetmehtet/
+    type: place
+    subType: settlement
+held_by: # every affiliation whose `domains` names this one
+  - title: The Nome of Ankhsetun
+    url: /thalorna/affiliation-nomenkhstn/
+    type: affiliation
+    subType: polity
+
+# on an affiliation
+holdings: # every place its `domains` names
+  - title: Ankhsetun
+    url: /thalorna/place-ankhsetunnome/
+    type: place
+    subType: region
+```
+
+- **`contains` and `holdings` are sorted by `subType`, then `title`**;
+  `held_by` by `title`. An entry carries `subType` where the note declares
+  one.
+- **A key is present only when it has an entry.** A place nobody holds and
+  nothing sits within carries neither key; an affiliation whose `domains` is
+  empty carries no `holdings`. The theme's silent-disappear convention, kept
+  at the source.
+- **`domains` names what an affiliation holds directly, and is never
+  expanded.** A polity whose `domains` names a region holds the region; the
+  settlements within it are reached through the region's `contains`, and are
+  not repeated in the polity's `holdings`. Tenure runs through
+  `affiliation.parents` — a house of its earl, an earl of the crown — and
+  geography through `place.parents`. A subinfeudated manor sits in one region
+  by the second and under a lord of another polity by the first, and both
+  pages say so.
+- **A dependency's places and affiliations take part.** A fetched index entry
+  carries the `parents` and `domains` its record stated, so a place another
+  package publishes is listed within a local region, and a house another
+  package publishes is named on the local manor it holds. A local note
+  declaring a shortcode shadows a fetched entry declaring the same one.
+- **`url` composes `<base><slug>/`**, as every `related` entry does.
+
+All three are derived, never authored: a note that writes one has it
+replaced. The theme renders each list as a table on the page.
+
+### A place page carries the map from that place
+
+A place that states a border or a route, or is named in one, has a map from
+it — the drawing `content-build map --from` makes, with the place at the
+centre and each neighbour at its bearing. The site build draws that map for
+every such place and writes it with the page: the page is a leaf bundle,
+`place-<shortcode>/index.md`, the drawing sits beside it as
+`from-<shortcode>.svg`, and the front matter names it:
+
+```yaml
+map: from-kthrmr.svg
+```
+
+The theme's "From here" panel reads the key, inlines the file as a page
+resource, and so every place name on the map is a link to that place's page.
+What the build guarantees:
+
+- **The address does not move.** A bundled page states the same `url` a flat
+  one does, `/<slug>/`, so `place-kthrmr/index.md` publishes exactly where
+  `place-kthrmr.md` would.
+- **Every name links through the site base.** The map is drawn with the base
+  the pages are served under, so each `href` composes `<base><slug>/` the way
+  every other href the build renders does.
+- **It is written for inlining.** No XML prologue, no DOCTYPE, no comment, no
+  reference to anything outside the file; the root carries a `viewBox` and no
+  fixed width or height, so the theme sizes it to the column.
+- **A place with no relation carries nothing**: no file beside it, no `map`
+  key, and the page stays a flat file. So does every page that is not a place.
+- **A site never fails for want of a map.** GraphViz draws; when it is not
+  installed the build says so once, as a warning naming what to install, and
+  every page is written as it would be without maps. `site.maps: false` in
+  `package-build.config.yaml` draws nothing and asks nothing of GraphViz.
+
+`map` is derived, never authored: a note that writes one has it replaced when
+the build draws a map, and dropped when there is none to draw.
+
 ### Why the output location is fixed
 
 The content mount is a build artifact and is **deleted on every run**, so that a

package/bin/content-build.mjs

@@ -83,6 +83,7 @@ import {
 import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
 import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
+import { lintNoteStates } from "../engine/stub-lint.mjs";
 import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
 import { lintContentIcons } from "../engine/content-icons.mjs";
@@ -1004,6 +1005,17 @@ function lintCommand() {
                     config,
                 });
 
+                // Whether every empty body is a stub on purpose, 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
+                // teaches its reader to stop looking at it.
+                const states = lintNoteStates(root, {
+                    records,
+                    contentPackage: config.contentPackage,
+                });
+                for (const line of states.summary) log.info(line);
+
                 const findings = [
                     ...addresses.findings,
                     ...frontmatter.findings,
@@ -1012,6 +1024,7 @@ function lintCommand() {
                     ...icons.findings,
                     ...html.findings,
                     ...images.findings,
+                    ...states.findings,
                 ];
                 // Only an **error** fails the run. Every finding was an error
                 // by then, so this changes nothing on its own —
@@ -1404,14 +1417,15 @@ function contentIndexCommand() {
         handler: (argv) => {
             try {
                 const config = loadPackConfig();
-                const { file, notes, bytes } = emitContentIndex({
+                const { file, notes, bytes, full, draft, stub } = emitContentIndex({
                     config,
                     ...(argv.root ? { contentBase: argv.root } : {}),
                     ...(argv.out ? { outDir: argv.out } : {}),
                 });
                 log.info(
                     `${config.contentPackage} → ${path.relative(process.cwd(), file)} ` +
-                        `(${notes} notes, ${Math.round(bytes / 1024)} KiB)`,
+                        `(${notes} notes — ${full} full, ${draft} draft, ` +
+                        `${stub} stub — ${Math.round(bytes / 1024)} KiB)`,
                 );
             } catch (err) {
                 reportFailure(err);
@@ -1515,7 +1529,8 @@ function pdfCommand() {
  * wikilink resolution, code-fence protection and the foreign-manifest merge —
  * happens here, from configuration. So does the Hugo configuration: the whole
  * source tree Hugo reads lands under `build/hugo/`, and the consumer's script
- * runs Hugo over it.
+ * runs Hugo over it. With `site.maps` on and GraphViz installed, every place
+ * page with a border or a route carries the map from that place.
  *
  * **The Hugo configuration is generated before anything is written.** Its
  * sources — `package.json`'s `homepage`, the cached navigation, the installed
@@ -1653,10 +1668,17 @@ function siteCommand() {
                     return;
                 }
 
+                // What drawing the maps found: warnings, every one. A site
+                // never fails for want of a map, so none of these touches the
+                // exit code — GraphViz absent is one line naming what to
+                // install, and every page is written as it would be without.
+                for (const f of result.mapFindings) emitDiagnostic(f);
+
                 const s = result.stats;
                 log.info(
                     `wrote ${s.homepages ?? 0} homepage(s) + ` +
-                        `${s.content ?? 0} content page(s) to ` +
+                        `${s.content ?? 0} content page(s), ` +
+                        `${s.maps ?? 0} with a map, to ` +
                         `${path.relative(process.cwd(), s.out)}`,
                 );
                 const { file } = writeHugoConfig(config, hugo);

package/content-config.mjs

@@ -772,6 +772,7 @@ const SITE_KEYS = [
     "notfound",
     "hugo",
     "search",
+    "maps",
 ];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
@@ -1711,9 +1712,11 @@ const SITE_INDEX_MESSAGE =
  * shared with the link manifest so the two cannot disagree about where a
  * page is.
  *
- * `search` is the one switch here: whether `package-build site-root` writes a
- * search index beside the rendered pages. On by default — every site carries
- * one unless it says otherwise.
+ * Two switches sit here, both on by default. `search` is whether
+ * `package-build site-root` writes a search index beside the rendered pages.
+ * `maps` is whether `content-build site` draws the map from each place that
+ * states a border or a route and writes it into that place's page — a site
+ * carries both unless it says otherwise.
  *
  * **What the site publishes is the homepage and the content tree, and nothing
  * beside them.** A page of documentation is a note — `type: doc`, addressed
@@ -1739,6 +1742,7 @@ function normalizeSite(value) {
         notfound: null,
         hugo: Object.freeze({}),
         search: true,
+        maps: true,
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
@@ -1795,6 +1799,7 @@ function normalizeSite(value) {
         notfound: normalizeSiteNotfound(input.notfound),
         hugo: normalizeSiteHugo(input.hugo),
         search: optionalBoolean(input.search, "site.search", true),
+        maps: optionalBoolean(input.maps, "site.maps", true),
     });
 }
 

package/docs/api.md

@@ -412,6 +412,29 @@ Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book.
 | `linkToUuid`           | `linkToUuid(value)`                   | `string`  | drawing a link value as a Foundry document reference                     |
 | `sectionHasContent`    | `sectionHasContent(section)`          | `boolean` | deciding whether a section holds anything worth drawing                  |
 
+### `engine.noteState`
+
+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                    |
+| `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 the prose a reader meets, with a wikilink counting as the one word it renders                      |
+
+### `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.
+
+| Export             | Signature                                                  | Returns                                             | Use it when                                                                                   |
+| ------------------ | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `SHORT_BODY_WORDS` | `const SHORT_BODY_WORDS`                                   | `number`                                            | reading the word count below which an unmarked body is asked whether it is a draft            |
+| `lintNoteStates`   | `lintNoteStates(contentBase, { records, contentPackage })` | `{findings, counts, byType, oldestDrafts, summary}` | checking a tree's states and counting the ladder, from the corpus the command already derived |
+
 ### `engine.placeRelations`
 
 What a place is next to (`data.borders`) and reachable from (`data.routes`): the closed sets both draw from, stated once for the lint, the specification and a consumer drawing a map, and the checks that hold a note to them and to the note at the other end.
@@ -429,6 +452,42 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 | `checkBorders`    | `checkBorders(note, { index })` | `object[]`          | linting a place's `borders` — targets, values, once per pair, no parent or child, and reciprocity with the other end |
 | `checkRoutes`     | `checkRoutes(note, { index })`  | `object[]`          | linting a place's `routes` — as `checkBorders`, plus `mode`, `days` and `terrain`, once per pair per mode            |
 
+### `engine.holdings`
+
+What lies within a place, who holds it, and what an affiliation holds — read off `data.parents` and `data.domains` across this package and every fetched index, inverted into the `contains`, `held_by` and `holdings` lists the site build writes — and the tenure check `content-build lint` runs on a place.
+
+| Export                 | Signature                            | Returns                 | Use it when                                                                                                                  |
+| ---------------------- | ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `HOLDINGS_KEYS`        | `const HOLDINGS_KEYS`                | `readonly string[]`     | the three derived keys — `contains`, `held_by`, `holdings` — which a note cannot author                                      |
+| `HELD_SUBTYPES`        | `const HELD_SUBTYPES`                | `readonly string[]`     | the place subTypes tenure is checked on — `settlement`, `site`, `structure`                                                  |
+| `holdingsNode`         | `holdingsNode(fm, { title, url })`   | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation               |
+| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)` | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                   |
+| `holdingsPages`        | `holdingsPages(nodes)`               | `Map<string, Holdings>` | inverting `parents` and `domains` into each page's sorted lists, keyed by URL, for every page with at least one entry        |
+| `shortcodesOf`         | `shortcodesOf(value)`                | `string[]`              | the shortcodes a `parents` or `domains` value names — bare, addressed or wikilinked — empties dropped and repeats collapsed  |
+| `checkHeld`            | `checkHeld(note, { index })`         | `object[]`              | linting a place's tenure — a settlement, site or structure no affiliation's `domains` names is a warning at its `type:` line |
+
+### `engine.populations`
+
+Whether a world's population figures agree from the region down — the polities and regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `content-build lint` runs all four as warnings.
+
+| Export                  | Signature                                | Returns             | Use it when                                                                                                  |
+| ----------------------- | ---------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `POPULATION_TOLERANCE`  | `const POPULATION_TOLERANCE`             | `number`            | how far a figure written to two significant digits may round below what it contains before that is a finding |
+| `POPULATION_RULES`      | `const POPULATION_RULES`                 | `readonly object[]` | the rules in order, each its `name` — the prefix its findings carry — and what it `describe`s                |
+| `checkPopulation`       | `checkPopulation(note, { index })`       | `object[]`          | linting a place's `population` — over-held land, an over-full region, and an oversized settlement            |
+| `checkCitedPopulations` | `checkCitedPopulations(note, { index })` | `object[]`          | linting a `doc` note's cited figures, each located at the `~figure` that states it                           |
+
+### `engine.marketClass`
+
+What trade a settlement supports (`data.market`): the six-step scale, stated once for the lint, the author-facing reference and the specification, and the check that holds a note's value to it.
+
+| Export           | Signature              | Returns             | Use it when                                                                                       |
+| ---------------- | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
+| `MARKET_CLASSES` | `const MARKET_CLASSES` | `readonly object[]` | the scale in order, each step its `value`, the `name` a settlement of it goes by, and its `trade` |
+| `isMarketClass`  | `isMarketClass(value)` | `boolean`           | asking whether an authored value names a class, a quoted number included                          |
+| `marketClass`    | `marketClass(value)`   | `object\|undefined` | the class a value names, for rendering what a number means                                        |
+| `checkMarket`    | `checkMarket(note)`    | `object[]`          | linting a place's `market` — a value off the scale, located at the value that states it           |
+
 ### `engine.mapPlaces`
 
 The places a map is drawn from — this package's index records and every fetched dependency's entries, read through one shape — and what their `parents` say: the world, the continents, each place's continent, and everything the containment tree can get wrong, reported as findings located at the entry that states it.
@@ -437,6 +496,7 @@ The places a map is drawn from — this package's index records and every fetche
 | --------------------- | ---------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `placesFromRecords`   | `placesFromRecords(records, { contentBase, base })`              | `MapWorld`    | reading this package's places and polities out of its index records, with a page URL each where a site base is given     |
 | `loadMapWorld`        | `loadMapWorld({ config, contentBase, base, problems })`          | `MapWorld`    | loading the world a map is drawn from — this package's index and every declared dependency's                             |
+| `mapWorld`            | `mapWorld({ records, foreignIndex, contentBase, base, config })` | `MapWorld`    | the same world out of records and indexes a caller already holds, as the site build does                                 |
 | `analyzeContainment`  | `analyzeContainment(places, polities)`                           | `Containment` | finding the world, the continents, each place's continent and the anomalies of `parents`                                 |
 | `subtreeOf`           | `subtreeOf(analysis, root)`                                      | `Set<string>` | every place beneath one, by following `parents` downward                                                                 |
 | `containmentFindings` | `containmentFindings(analysis, places, { contentBase, config })` | `object[]`    | the anomalies as `file:line:column: severity: message` findings — no parent, an unresolved parent and a cycle are errors |
@@ -485,6 +545,7 @@ GraphViz, as the map command reaches it: a build-time tool of that command alone
 | Export                   | Signature                                               | Returns             | Use it when                                                                                |
 | ------------------------ | ------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
 | `GRAPHVIZ_ENGINES`       | `const GRAPHVIZ_ENGINES`                                | `readonly string[]` | the engines the map command may ask for — `dot`, `twopi`, `neato`                          |
+| `GRAPHVIZ_INSTALL`       | `const GRAPHVIZ_INSTALL`                                | `string`            | what installs GraphViz, as the clause every "not installed" message ends with              |
 | `findGraphviz`           | `findGraphviz(engine, { env, fallbacks })`              | `string\|undefined` | finding an engine's binary on `PATH` or in the directories a package manager installs into |
 | `graphvizMissingMessage` | `graphvizMissingMessage(engine)`                        | `string`            | saying an engine is not installed, and what installs it                                    |
 | `renderDot`              | `renderDot(dotPath, outPath, { binary, format, args })` | `{warnings}`        | rendering a `.dot` file, the engine's warnings returned and a non-zero exit thrown         |
@@ -500,6 +561,16 @@ GraphViz, as the map command reaches it: a build-time tool of that command alone
 | `relatedPlaces` | `relatedPlaces(places)`                                                                                                                               | `string[]`                     | every place that states, or is named in, a border or a route                  |
 | `buildMaps`     | `buildMaps({ world, outDir, tree, root, from, chart, horizon, travel, engine, rankdir, nodesep, ranksep, scale, polities, locate, requireGraphviz })` | `{written, findings, skipped}` | drawing any of the four from a loaded world                                   |
 
+### `engine.siteMaps`
+
+The map from each place, drawn for the site: `content-build site` draws the map from every place of this package that states, or is named in, a border or a route — with the site's base, so every name links through it — and the page writer lays each drawing beside its page as `from-<shortcode>.svg` and names it in the front matter as `map`. GraphViz absent is one warning and no map; `site.maps: false` draws none.
+
+| Export         | Signature                                                       | Returns            | Use it when                                                                                                     |
+| -------------- | --------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `SITE_MAP_DIR` | `const SITE_MAP_DIR`                                            | `string`           | where the site build draws below a package's root, `build/map/site`                                             |
+| `inlineSvg`    | `inlineSvg(svg)`                                                | `string`           | rewriting a GraphViz SVG for inlining — no prologue, no comment, no `xlink:`, the root sized by `viewBox` alone |
+| `drawSiteMaps` | `drawSiteMaps({ records, foreignIndex, config, base, locate })` | `{maps, findings}` | drawing the map from every related place of this package, keyed by the URL of the page that carries it          |
+
 ### `engine.systems`
 
 The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.
@@ -615,19 +686,19 @@ Emitting this package's cross-package link manifest. `engine/content-address.mjs
 
 Emitting this package's content index. Every content build already walks the whole note tree and parses every note's frontmatter — the pack compilers, the site build, and the content-table expander each do it — and every one of them throws the result away when it finishes. So nothing outside a build can ask a question about the content: "which beings carry no `kbcat`?", "what does this table actually select?", "did that type rename leave anything behind?" have no answer short of writing a throwaway script that re-walks the tree. Eight dead Bestiary tables shipped for weeks behind exactly that gap.
 
-| Export                  | Signature                                                                                               | Returns                                                                                                                                                                                                                  | Use it when                                                                                                                                                                                                               |
-| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                                     | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well. | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                                                                |
-| `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                          | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                      | Recursively sort an object's keys, so serialization is order-independent.                                                                                                                                                 |
-| `asciiName`             | `function asciiName(name)`                                                                              | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                           | A note's display name reduced to printable 7-bit ASCII.                                                                                                                                                                   |
-| `asciiAliases`          | `function asciiAliases(aliases)`                                                                        | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                    | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                                                                       |
-| `serializeContentIndex` | `function serializeContentIndex(records)`                                                               | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                           | Serialize records as JSON Lines.                                                                                                                                                                                          |
-| `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems })`                                   | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                        | The index records for a content tree, without writing anything.                                                                                                                                                           |
-| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config })`                                                     | {{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.                        | Emit this package's content index.                                                                                                                                                                                        |
-| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest })`         | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                      | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                      |
-| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems })` | `Array<Record<string, any>>`                                                                                                                                                                                             | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file |
+| Export                  | Signature                                                                                               | Returns                                                                                                                                                                                                                                                                     | Use it when                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                                     | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well.                                                    | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                                                                |
+| `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                          | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                                                                         | Recursively sort an object's keys, so serialization is order-independent.                                                                                                                                                 |
+| `asciiName`             | `function asciiName(name)`                                                                              | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                                                                              | A note's display name reduced to printable 7-bit ASCII.                                                                                                                                                                   |
+| `asciiAliases`          | `function asciiAliases(aliases)`                                                                        | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                                                                       | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                                                                       |
+| `serializeContentIndex` | `function serializeContentIndex(records)`                                                               | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                                                                              | Serialize records as JSON Lines.                                                                                                                                                                                          |
+| `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems })`                                   | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                                                                           | The index records for a content tree, without writing anything.                                                                                                                                                           |
+| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config })`                                                     | {{file: string, notes: number, assets: number, records: number, 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. | Emit this package's content index.                                                                                                                                                                                        |
+| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest })`         | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                                                                         | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                      |
+| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems })` | `Array<Record<string, any>>`                                                                                                                                                                                                                                                | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file |
 
-`engine.contentIndex` also re-exports seven names from neighbouring leaf modules, at this same import path:
+`engine.contentIndex` also re-exports eight names from neighbouring leaf modules, at this same import path:
 
 | Export                | Signature                        | Returns                                                        | Use it when                                                                                                                                                                      |
 | --------------------- | -------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -636,6 +707,7 @@ Emitting this package's content index. Every content build already walks the who
 | `noteFile`            | `noteFile(contentBase, record)`  | `string` — the note's absolute path                            | composing an index record's `file.path` (recorded relative, for a byte-stable artifact) back into an openable absolute path                                                      |
 | `authoredFrontmatter` | `authoredFrontmatter(record)`    | `Record<string, any>` — the frontmatter without `DERIVED_KEYS` | reading back exactly what a note authored from its index record, so a pass can lint or compile from the index without reasoning about derived fields as if the author wrote them |
 | `isNoteRecord`        | `isNoteRecord(record)`           | `boolean`                                                      | telling a note's own record apart from its documentation journal's and from an asset's, when enumerating the corpus                                                              |
+| `isStub`              | `isStub(record)`                 | `boolean`                                                      | telling a stub — a note with an empty body — apart from a note that publishes a page; asked of the absent address, which is the whole signal                                     |
 | `isAssetRecord`       | `isAssetRecord(record)`          | `boolean`                                                      | telling a record that addresses a file apart from one that addresses a note; the `asset` block is what marks it                                                                  |
 | `recordPath`          | `recordPath(record)`             | `string` — the path the record names inside its package        | ordering or reporting across both record shapes: a note names the `.md` it was parsed from, an asset the file it is                                                              |
 
@@ -694,20 +766,20 @@ The toolchain's own content index — the files it ships, addressed. Every other
 
 Publishing a content tree as a website. Compiling a content tree into compendium packs is `content-build package compile`. Publishing the _same tree_ as a website was a script each consumer wrote for itself — 473 code lines in `sohl` and 462 in `sohl-thalorna`, 87 of them identical — and the copies drifted in ways neither repository could see. `sohl-thalorna` reimplemented four things this package already exported, not because it needed different behaviour but because its script predates the extraction. That is the failure a command removes: a consumer cannot accidentally reimplement one.
 
-| Export                | Signature                                         | Returns                                                                                                                                | Use it when                                                                |
-| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                 |
-| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.  |
-| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage as the package root's `_index.md`.                    |
-| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.           |
-| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                          |
-| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                       |
-| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.               |
-| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                     |
-| `pageDestination`     | `function pageDestination(page)`                  | —                                                                                                                                      | Where a page is written, relative to the output root.                      |
-| `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                             |
-| `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                        |
-| `buildSite`           | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found. |
+| Export                | Signature                                         | Returns                                                                                                                                | Use it when                                                                                                           |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                                                            |
+| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.                                             |
+| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage as the package root's `_index.md`.                                                               |
+| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.                                                      |
+| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                                                                     |
+| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                                                                  |
+| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.                                                          |
+| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                                                                |
+| `pageDestination`     | `function pageDestination(page, { bundle })`      | —                                                                                                                                      | Where a page is written, relative to the output root: flat, or as a leaf bundle when it carries a file beside itself. |
+| `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                                                                        |
+| `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                                                                   |
+| `buildSite`           | `buildSite({ config, sqlTables, locate })`        | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
 
 ### `engine.contentLint`
 
@@ -941,6 +1013,7 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | `unlabelledLinkMessage`    | `function unlabelledLinkMessage(target)`                   | {string} The message, unpunctuated at the end as a finding is.  | What an author writing an unlabelled link is told, in one place.                |
 | `LINK_FINDING_REASONS`     | `const LINK_FINDING_REASONS`                               | —                                                               | Every way a link can fail, named once for all three resolvers.                  |
 | `unresolvedAddressMessage` | `function unresolvedAddressMessage(target)`                | {string} The message, unpunctuated at the end as a finding is.  | What an author writing an address that resolves to nothing is told.             |
+| `stubAddressMessage`       | `function stubAddressMessage(target, file)`                | {string} The message, unpunctuated at the end as a finding is.  | What an author linking to a stub is told, naming the file to open.              |
 | `ambiguousAddressMessage`  | `function ambiguousAddressMessage(target, packages`        | {string} The message.                                           | What an author writing a short address more than one package publishes is told. |
 | `linkFindingMessage`       | `linkFindingMessage({ reason, target, packages, anchor })` | {string} The message.                                           | The message for one link finding, whichever resolver found it.                  |
 | `isSamePage`               | `isSamePage({ target, anchor })`                           | {boolean} True when the link is same-page.                      | Whether a parsed link addresses a section of the page it is written on.         |