@heroiclands/package-build 23.13.0 → 24.0.1

package/docs/api.md

@@ -295,19 +295,18 @@ Schema fields a note may never author, because the document writes them during p
 
 The package homepage: a note that compiles to a page rather than a compendium document, hand-authored at the conventional shortcode `root`, checked for its address fields and for uniqueness across the tree.
 
-| Export                       | Signature                             | Returns                        | Use it when                                                                                |
-| ---------------------------- | ------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
-| `HOMEPAGE_TYPE`              | `const HOMEPAGE_TYPE`                 | —                              | naming the note type that compiles to the package homepage                                 |
-| `HOMEPAGE_FIELDS`            | `const HOMEPAGE_FIELDS`               | —                              | declaring what a homepage note may write under `sohl:` — nothing                           |
-| `HOMEPAGE_SHORTCODE`         | `const HOMEPAGE_SHORTCODE`            | —                              | naming the shortcode a package front page conventionally takes                             |
-| `HOMEPAGE_DESTINATION`       | `const HOMEPAGE_DESTINATION`          | —                              | naming the file a homepage is written to, `_index.md` at the site root                     |
-| `isHomepage`                 | `isHomepage(fm)`                      | `boolean`                      | checking whether a note's frontmatter declares the homepage type                           |
-| `HOMEPAGE_REFUSED_FIELDS`    | `const HOMEPAGE_REFUSED_FIELDS`       | —                              | naming the top-level fields a homepage refuses, and what each would decide                 |
-| `checkHomepageAddressFields` | `checkHomepageAddressFields(fm, ...)` | one finding per issue          | checking what the address rule says about one homepage note's top-level fields             |
-| `checkHomepageCount`         | `checkHomepageCount(found, ...)`      | one finding per offending note | requiring exactly one homepage note in a content tree                                      |
-| `homepageTitle`              | `homepageTitle(fm, config)`           | `string`                       | resolving the title a homepage publishes under, defaulting to the package's manifest title |
-| `homepageFrontmatter`        | `homepageFrontmatter(fm, ...)`        | `object`                       | assembling the frontmatter a homepage publishes with, note plus derived values             |
-| `homepageAddresses`          | `homepageAddresses(body)`             | `Array<{field, url, kind}>`    | finding every address a homepage carries — the markdown links in its body                  |
+| Export                       | Signature                             | Returns                        | Use it when                                                                                                      |
+| ---------------------------- | ------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `HOMEPAGE_TYPE`              | `const HOMEPAGE_TYPE`                 | —                              | naming the note type that compiles to the package homepage                                                       |
+| `HOMEPAGE_FIELDS`            | `const HOMEPAGE_FIELDS`               | —                              | declaring what a homepage note may write under `sohl:` — nothing                                                 |
+| `HOMEPAGE_SHORTCODE`         | `const HOMEPAGE_SHORTCODE`            | —                              | naming the shortcode a package front page conventionally takes                                                   |
+| `isHomepage`                 | `isHomepage(fm)`                      | `boolean`                      | checking whether a note's frontmatter declares the homepage type                                                 |
+| `HOMEPAGE_REFUSED_FIELDS`    | `const HOMEPAGE_REFUSED_FIELDS`       | —                              | naming the top-level fields a homepage refuses, and what each would decide                                       |
+| `checkHomepageAddressFields` | `checkHomepageAddressFields(fm, ...)` | one finding per issue          | checking what the address rule says about one homepage note's top-level fields                                   |
+| `checkHomepageCount`         | `checkHomepageCount(found, ...)`      | one finding per offending note | requiring exactly one homepage note in a content tree                                                            |
+| `homepageTitle`              | `homepageTitle(fm, config)`           | `string`                       | resolving the title a homepage publishes under, defaulting to the package's manifest title, then to `site.title` |
+| `homepageFrontmatter`        | `homepageFrontmatter(fm, ...)`        | `object`                       | assembling the frontmatter a homepage publishes with, note plus derived values                                   |
+| `homepageAddresses`          | `homepageAddresses(body)`             | `Array<{field, url, kind}>`    | finding every address a homepage carries — the markdown links in its body                                        |
 
 ### `engine.noteSchemas`
 
@@ -552,6 +551,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                                 |
+| `placeShortcodes`     | `placeShortcodes(value)`                                         | `string[]`    | reading a list of places — `parents`, a being's `homes`, a scenario's `locations` — as lower-case shortcodes             |
 | `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 |
@@ -615,7 +615,7 @@ The npm-installed Graphviz runtime draws SVG maps. The `.dot` source stays besid
 
 ### `engine.siteMaps`
 
-The map from each place, drawn for the site: `package-build site` draws the map from every place of this package given a **From here** section — with the site's base, so every name links through it — and sets each drawing inline in that section, where its place names stay links. `site.maps: false` gives no place the section, and nothing is drawn.
+The map from each place, drawn for the site: `package-build site build` draws the map from every place of this package given a **From here** section — with the site's base, so every name links through it — and sets each drawing inline in that section, where its place names stay links. `site.maps: false` gives no place the section, and nothing is drawn.
 
 | Export                | Signature                                               | Returns            | Use it when                                                                                                     |
 | --------------------- | ------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -723,7 +723,7 @@ resolved value: the culture a place or affiliation inherits through
 
 ### `engine.markdownExpressions`
 
-`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`, in the calendar it names or else the note's resolved calendar, which it reads from `dates.noteCalendars` — the map a reckoning context built over content-index records carries; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. The `ref` helper links to a captioned item by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
+`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`, in the calendar it names or else the note's resolved calendar, which it reads from `dates.noteCalendars` — the map a reckoning context built over content-index records carries; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. The `ref` helper links to a captioned item by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve.
 
 | Export                      | Signature                                  | Returns                | Use it when                                      |
 | --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
@@ -1294,33 +1294,56 @@ The toolchain's own content index — the files it ships, addressed. Every other
 
 Publishing a content tree as a website. `collectContentPages` gathers authored
 pages and link findings, while `collectHomepages` gathers package homepages.
-`writeHomepages` places those homepages at each package's site root. The same
+`homepageData` gives each homepage's frontmatter and body, and `renderPages` renders the content pages. The same
 content tree can also compile into Foundry compendium packs.
 
-| 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`           | `siteGates(pages, findings, options)`             | {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: `<slug>.md`, flat under the mount. |
-| `renderSitePage`      | `renderSitePage(page, options)`                   | `{body, data, resolved, tableErrors, secretErrors, wikiErrors, imageErrors}`                                                             | Transform one page with the same passes the site writer uses.                            |
-| `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.                                                      |
-| `sitePageDecorator`   | `sitePageDecorator(config, index)`                | Function                                                                                                                                 | Add the site's infobox and being metadata to a rendered page.                            |
-| `buildSite`           | `buildSite({ config, sqlTables })`                | `{{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.               |
+| 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>/`.                                                  |
+| `homepageData`        | `homepageData(pages, config, options)`           | `Array<{file, body, data}>`                                                                                                                          | Each homepage's frontmatter as its page publishes it, and its body.                                                        |
+| `siteGates`           | `siteGates(pages, findings, options)`            | {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.                                                                                       |
+| `siteBuildFailed`     | `siteBuildFailed(result)`                        | `boolean`                                                                                                                                            | Whether a gate fired or a note is in error, so the site is not to be deployed.                                             |
+| `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.                                                                                     |
+| `renderSitePage`      | `renderSitePage(page, options)`                  | `{body, data, resolved, tableErrors, secretErrors, wikiErrors, imageErrors}`                                                                         | Transform one page with the same passes the site writer uses.                                                              |
+| `renderPages`         | `function renderPages(pages, options)`           | `{{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}`                                                   | Renders every page.                                                                                                        |
+| `resolveSitePass`     | `function resolveSitePass(name, options)`        | `{{beforeLinks?: Function}}` The bundle.                                                                                                             | Resolves `site.pass` to its bundle.                                                                                        |
+| `sitePageDecorator`   | `sitePageDecorator(config, index)`               | Function                                                                                                                                             | Add the site's infobox and being metadata to a rendered page.                                                              |
+| `buildSite`           | `buildSite({ config, sqlTables })`               | `{{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null, site?: object}}` | Collects, checks and renders a content tree's pages, and reports what it found; returns each page for the site's renderer. |
 
 `siteGates` takes `{ config, records, sqlTables? }`. Pass the prepared
 `sqlTables` map so anchors emitted by automatic dictionary sections are present in the
 index for checking page links.
 
+### `engine.contentRender`
+
+`createRenderer(target, options?)` builds the one markdown-it configuration every target renders through. `target` is `"foundry"`, `"web"`, `"preview"` or `"book"`. The renderer holds the configured parser (`md`), the names of the plugins installed (`plugins`), and three functions: `prepare` writes the constructs markdown-it has no syntax for — marked text, captioned items, named blocks, verse and alerts — as HTML between blank lines; `render` prepares and renders to HTML; `renderInline` renders one inline run. The `book` target parses only, and its Typst stage reads the tokens.
+
+| Export           | Signature                          | Returns                                                      | Use it when                                                                              |
+| ---------------- | ---------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `createRenderer` | `createRenderer(target, options?)` | `{ target, md, plugins, prepare, render, renderInline }`     | Rendering a note body for one target with the rules every target shares.                 |
+| `RENDER_TARGETS` | Constant                           | The four targets                                             | Checking that a target is one the renderer is built for.                                 |
+| `highlightCode`  | `highlightCode(code, language)`    | highlight.js markup, or `""` for a language it does not know | Highlighting a fenced block's code at build time.                                        |
+| `inertHtml`      | `inertHtml(markdown)`              | The markdown with each authored tag made inert               | Preparing a buffer for the `preview` target, which writes the only HTML its parser sees. |
+
+`createRenderer("preview", { source: true })` shows wikilinks, spans and expressions as highlighted authored source; without `source` the preview renders them. `options.icons` is the icon registry, or a function that returns it; `options.images` is `{ resolveSrc, lookupAsset }`, which resolves a body image's address and finds its asset.
+
+### `engine.previewIndex`
+
+`previewIndex({ config, records, foreign? })` builds what [`renderPreview`](#enginesitepreview) takes as `index`: the link index, the asset address space, the languages' maps, the icon registry and an `expand` function that resolves a buffer's links, embeds, expressions and figure numbers as the website does. `records` are the content index's records and `foreign` the dependencies' indexes. Build it once per index and reuse it for every render.
+
+| Export         | Signature                                    | Returns                                | Use it when                                                              |
+| -------------- | -------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
+| `previewIndex` | `previewIndex({ config, records, foreign })` | `{ runs, icons, lookupAsset, expand }` | An editor holds a content index and wants the preview to render with it. |
+
 ### `engine.sitePreview`
 
-`renderPreview(text, { dark = false, infobox = true, file = "", currentDate = "720.1" })` renders the current Markdown buffer directly to HTML. Frontmatter is optional. It needs no package configuration, saved note, content tree, dependency cache, database or Pandoc installation. The result is `{ ok, html, frontmatter, findings }`; `file` only labels diagnostics. Malformed frontmatter produces a warning and remains visible without preventing a preview update.
+`renderPreview(text, { dark = false, infobox = true, file = "", currentDate = "720.1", index })` renders the current Markdown buffer directly to HTML. Frontmatter is optional. Without `index` it needs no package configuration, saved note, content tree, dependency cache, database or Pandoc installation. The result is `{ ok, html, frontmatter, findings }`; `file` only labels diagnostics. Malformed frontmatter produces a warning and remains visible without preventing a preview update.
+
+With `index`, from [`engine.previewIndex`](#enginepreviewindex), the preview expands the buffer as the website expands a page and renders it through the same renderer: links resolve, embeds draw their pictures, marked text is mapped and set in its face, icons draw, figure numbers carry their asset roles, and a concealed link is concealed. A query, which a buffer cannot run, stays highlighted source.
 
 | Export                   | Signature                       | Returns                               | Use it when                                                            |
 | ------------------------ | ------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
@@ -1339,7 +1362,7 @@ const result = renderPreview(currentBufferText, { dark: true });
 showDiagnostics(result.findings);
 ```
 
-Ordinary Markdown, definition lists, footnotes, alert boxes, verse, captions, local figures and container blocks render locally. Alerts reuse the four shared icons and titles, accept custom titles and nested alerts, and have opaque tinted backgrounds in both modes. Definition terms are bold; definitions retain ordinary Markdown styling. Wikilinks and image embeds retain their entire authored source: blue opening markers (including all of `![[`), brackets and pipes, purple addresses and anchors, bold foreground labels, and grey attributes. Spans retain their entire source in bold, with blue brackets and grey attributes. Code examples stay literal. Incomplete syntax remains visible while editing.
+Ordinary Markdown, definition lists, footnotes, alert boxes, verse, captions, local figures and container blocks render locally. Alerts reuse the four shared icons and titles, accept custom titles and nested alerts, and have opaque tinted backgrounds in both modes. Definition terms are bold; definitions retain ordinary Markdown styling. Wikilinks and image embeds retain their entire authored source: blue opening markers (including all of `![[`), brackets and pipes, purple addresses and anchors, bold foreground labels, and grey attributes. Spans retain their entire source in bold, with blue brackets and grey attributes. Code in a code span or an example fence stays literal, and a fence that names a language is highlighted. Incomplete syntax remains visible while editing.
 
 SQL and pagelist fences remain grey source, including delimiters. Calendar/date expressions, cross-note references and maps remain green source. A dependent call nested inside a pure helper preserves the entire outer expression. Pure helpers and scalar frontmatter expressions evaluate locally; same-note figure references and non-date event facts can resolve from this buffer. Infobox fields show authored values and green reference source; image and portrait wikilinks use the image syntax colors. Missing ages are calculated locally from neutral birth dates and `currentDate`, defaulting to `"720.1"`; authored ages, including `0`, take precedence. Unavailable ages remain `null` internally, have no infobox row, and render as empty text in `{{data.age}}`. Named-calendar birth dates remain unavailable without calendar context. Set `infobox: false` to omit the profile.
 
@@ -1498,24 +1521,6 @@ without a raw string it reads that file. The caller owns this map, and the
 link index leaves it unchanged. This source capture is separate from published
 metadata and has no persistent or cross-invocation cache.
 
-### `engine.webWikilinks`
-
-Wikilink resolution for the knowledgebase build. The same authored links the pack compilers turn into Foundry `@UUID` enrichers (see `./wikilinks.mjs`) become site-local hrefs here:
-
-| Export                 | Signature                                 | Returns                                                                                                                                           | Use it when                                                           |
-| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `frontmatterWikilinks` | `function frontmatterWikilinks(fm)`       | {Array<{path: string, link: string}>} In reading order; `path` is the dotted key path of the offending value (`government.summary`, `aliases.1`). | Every wikilink authored inside a frontmatter value.                   |
-| `resolveWebWikilinks`  | `function resolveWebWikilinks(body, ctx)` | {string} The body with wikilinks rewritten.                                                                                                       | Rewrites the wikilinks in a markdown body as KB-local markdown links. |
-
-Both `resolveWebWikilinks` and Foundry's `convertWikilinks` derive reference
-spoilers from the resolved note audience and secret-anchor metadata. A trailing
-`{.show}` bypasses automatic spoiler wrapping, without changing destination
-access. A web destination excluded by audience retains its label without an
-href. Same-note secret anchors follow the same rule; a whole-note link to a
-public note does not inherit individual secret sections. See the
-[authoring contract](authoring/links-and-markup.md#references-to-secret-subjects)
-for surface presentation.
-
 ### `engine.contentTables`
 
 Prepared SQL content tables are expanded into Markdown before link resolution.
@@ -1626,20 +1631,36 @@ source locations and frontmatter source slicing.
 
 ### `engine.wikilinks`
 
-Wikilink resolution for the pack compilers. Content notes link to one another with wikilinks rather than file paths:
-
-| Export               | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                                                    | Use it when                                                                                                                                                                |
-| -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads an accepted `doc<type>` input alias as its authored type.                                                                                                            |
-| `readQualifier`      | `function readQualifier(target, types, packages, noIndexPackages)`      | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"\|"no-content-index", package?: string} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type or no fetched index; or `null` when it is not an address at all. | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
-| `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                                                   | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
-| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | `{{byShortcode: Map<string, object>, types: Set<string>}}` `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                   | Builds the link-resolution tables for a content tree.                                                                                                                      |
-| `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                                          | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
-| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | `{{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}}` Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named.                    | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
+The link resolver. One authored `[[…]]` resolves the same way for every target, and each target writes the result in its own form: a Foundry journal gets an `@UUID[…]{label}` content link that survives import into a world, a web page a relative URL, and the book a cross-reference to the entry it prints. `resolveWikilinks` is the resolution; a `LinkView` is the index it reads (`packLinkView` over the pack compile's index, `siteLinkView` over the site index), and `LINK_WRITERS` holds each target's form. `convertWikilinks` and `resolveWebWikilinks` are the pack compile's and the site's entries to it.
+
+| Export                 | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                                                    | Use it when                                                                                                                                                                |
+| ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resolveItemDocType`   | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads an accepted `doc<type>` input alias as its authored type.                                                                                                            |
+| `readQualifier`        | `function readQualifier(target, types, packages, noIndexPackages)`      | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"\|"no-content-index", package?: string} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type or no fetched index; or `null` when it is not an address at all. | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
+| `slugify`              | `slugify(text)`                                                         | `string`                                                                                                                                                                                                                                                                                                                                                   | The heading and anchor slug: the rule that names a page also names a section within it.                                                                                    |
+| `anchorPageId`         | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                                                   | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
+| `buildWikilinkIndex`   | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | `{{byShortcode: Map<string, object>, types: Set<string>}}` `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                   | Builds the link-resolution tables for a content tree.                                                                                                                      |
+| `LINK_WRITERS`         | `const LINK_WRITERS`                                                    | `{foundry, web, book}`, each `(link: ResolvedLink) => string`                                                                                                                                                                                                                                                                                              | The form each target writes a resolved link in, a draft link, a link with nothing to open and an unresolved one.                                                           |
+| `resolveWikilinks`     | `function resolveWikilinks(markdown, { view, write, captionLabels })`   | `{{markdown: string, links: ResolvedLink[], findings: object[], resolved: object[]}}` The written body; every link's neutral resolution, in body order; each finding with its `reason`, `offset` and `occurrence`; and every destination outside the page.                                                                                                 | Resolve every wikilink in a body against one index and write each in one target's form.                                                                                    |
+| `packLinkView`         | `function packLinkView(index, { type, id, pack, docPack })`             | `LinkView`                                                                                                                                                                                                                                                                                                                                                 | The pack compile's index, answered with compendium UUIDs, for links written on one note.                                                                                   |
+| `convertWikilinks`     | `function convertWikilinks(markdown,`                                   | `{{markdown: string, links: ResolvedLink[], unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}}` Each `reason` is one of {@link LINK_FINDING_REASONS} — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named.                                       | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
+| `resolveReference`     | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                                          | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
+| `siteLinkView`         | `function siteLinkView(ctx, body)`                                      | `LinkView`                                                                                                                                                                                                                                                                                                                                                 | The site index, answered with URLs, for links written on one page.                                                                                                         |
+| `frontmatterWikilinks` | `function frontmatterWikilinks(fm)`                                     | {Array<{path: string, link: string}>} In reading order; `path` is the dotted key path of the offending value (`government.summary`, `aliases.1`).                                                                                                                                                                                                          | Every wikilink authored inside a frontmatter value.                                                                                                                        |
+| `resolveWebWikilinks`  | `function resolveWebWikilinks(body, ctx)`                               | {string} The body with embeds and wikilinks rewritten.                                                                                                                                                                                                                                                                                                     | Rewrites the embeds and wikilinks in a markdown body for the website, or for the book with `ctx.output` `"book"`.                                                          |
+
+Every target derives reference
+spoilers from the resolved note audience and secret-anchor metadata. A trailing
+`{.show}` bypasses automatic spoiler wrapping, without changing destination
+access. A web destination excluded by audience retains its label without an
+href. Same-note secret anchors follow the same rule; a whole-note link to a
+public note does not inherit individual secret sections. See the
+[authoring contract](authoring/links-and-markup.md#references-to-secret-subjects)
+for surface presentation.
 
 ### `engine.wikilinkSyntax`
 
-What a `[[…]]` **is**, before anything decides where it points. One authored link compiles to two different addresses — a Foundry `@UUID` enricher for the packs, a URL for the web — and those two destinations are the _only_ thing that legitimately differs. The syntax is the author's, and it is the same syntax whichever build is reading it.
+What a `[[…]]` **is**, before anything decides where it points. One authored link is written three ways — a Foundry `@UUID` content link for the packs, a URL for the web, a cross-reference for the book — and those forms are the _only_ thing that legitimately differs. The syntax is the author's, and it is the same syntax whichever build is reading it.
 
 | Export                     | Signature                                                  | Returns                                                         | Use it when                                                                                       |
 | -------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
@@ -1648,7 +1669,7 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | `readWikilink`             | `function readWikilink(inner, context, literal?)`          | Typed target or literal target with diagnostic source.          | Parse a link target using complete builder Address context.                                       |
 | `authoredLabel`            | `authoredLabel({ display })`                               | {string\|null} The label, or `null` when there is none to show. | The label an author actually supplied, or `null` when they supplied none.                         |
 | `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.                                    |
+| `LINK_FINDING_REASONS`     | `const LINK_FINDING_REASONS`                               | —                                                               | Every way a link can fail, named once for every reader of a link.                                 |
 | `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.                   |
@@ -2086,7 +2107,7 @@ const config = defineConfig({
 | `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`     | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                |
 | `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`     | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
 | `publishesContentPages`    | `publishesContentPages(config)`    | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                  |
-| `DERIVED_HUGO_KEYS`        | `const DERIVED_HUGO_KEYS`          | —                                                          | reading which Hugo keys `site.hugo` may not declare because the site build generates them, each naming its source (declaring one is an error naming the key); a dotted key covers everything beneath it                                  |
+| `siteBase`                 | `siteBase(config)`                 | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                          |
 
 ## `./config`
 
@@ -2100,13 +2121,13 @@ const config = loadPackageBuildConfig();
 console.log(config.stageDir);
 ```
 
-| Export                      | Signature                                 | Returns                        | Use it when                                                                                                                                                                     |
-| --------------------------- | ----------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`             | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)                                              |
-| `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                |
-| `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                    |
-| `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `package-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
-| `fail`                      | `fail(where, problem)`                    | `never`                        | rejecting a configured value from a sibling module, naming the dotted key path it was written under, so the loader can resolve it to a line and column                          |
+| Export                      | Signature                                 | Returns                        | Use it when                                                                                                                                                                       |
+| --------------------------- | ----------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`             | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)                                                |
+| `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                  |
+| `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                      |
+| `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `package-build site build` before the site settings are composed, not by `resolvePackageBuildConfig` itself |
+| `fail`                      | `fail(where, problem)`                    | `never`                        | rejecting a configured value from a sibling module, naming the dotted key path it was written under, so the loader can resolve it to a line and column                            |
 
 ## `./prettier`