@heroiclands/package-build 22.4.7 → 22.5.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @heroiclands/package-build
 
+## 22.5.1
+
+### Patch Changes
+
+**Unwritten notes**
+
+- A note left unwritten builds: an empty body no longer stops a package
+  compiling its packs.
+- An unwritten note offers no compendium link, so nothing sends a reader to a
+  journal that was never made.
+
+## 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

package/CONTENT.md

@@ -1093,6 +1093,66 @@ 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 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.
+
+**A document that would be empty is not created**, and the index then names no
+artefact — `uuid`, `path` and `address` are `null`. An unwritten note still
+compiles every document derived from `data:`, so an arcane talent is still its
+Item; what it compiles no journal for is its prose, because there is none. An
+infobox does not count as content: the panel renders `data:` the index already
+carries.
+
+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
@@ -1190,6 +1250,26 @@ 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
@@ -2054,7 +2134,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
 {

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);

package/docs/api.md

@@ -412,6 +412,30 @@ 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                                   |
+| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all |
+| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                             |
+| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
+| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting 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.
@@ -440,8 +464,20 @@ What lies within a place, who holds it, and what an affiliation holds — read o
 | `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.
@@ -651,19 +687,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                                                                                                                                                                      |
 | --------------------- | -------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -672,6 +708,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                                                              |
 
@@ -977,6 +1014,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.         |

package/docs/content-format.md

@@ -1657,6 +1657,108 @@ 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 one would not be empty | 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`**, which is the identity every diagnostic and every table reads.
+- **`foundry`**, naming each document that was made.
+
+#### A document that would be empty is not created
+
+> **If the resulting document would be empty, it is not created** — and the
+> index then names no artefact: `uuid`, `path` and `address` are `null`, which
+> is how a record says one was not made.
+
+The test is about the **output**, which is what lets one rule cover every case:
+
+| The note                           | The document                           | Made? |
+| ---------------------------------- | -------------------------------------- | ----- |
+| `place`, `lore`, `doc`, `scenario` | its JournalEntry, which _is_ the prose | no    |
+| any item type, `macro`             | the Item or Macro, from `data:`        | yes   |
+| the same note's documentation      | a JournalEntry of the same prose       | no    |
+| `map`                              | the Scene, from `data:`                | yes   |
+
+An unwritten arcane talent still compiles into its Item, because an Item is its
+`data:` and that is not empty. What it has no documentation journal for is the
+same thing an unwritten `place` has no journal for: there is nothing to put in
+one.
+
+**An infobox does not count as content.** The panel is a rendering of `data:`
+that the index already publishes, so an entry holding nothing else would tell a
+reader exactly what the record told them.
+
+Nothing anywhere names a document that was not made: a compendium UUID for one
+would send every consumer that resolves it to a document the pack does not hold.
+
+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 +2005,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:
@@ -3258,6 +3403,53 @@ a warning from `content-build lint`, `unheld land`, located at the note's
 `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).`,