@heroiclands/package-build 22.14.2 → 22.14.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @heroiclands/package-build
 
+## 22.14.3
+
+### Patch Changes
+
+Editors can preview a content page from unsaved text, including its tables, links, images, and GM passages.
+
+Setting orientation pages can be authored as setting guides, with the same links, tables, and GM passages as other guides.
+
+**Content authoring**
+
+- Beings can describe defining social ties, and place notes can identify their practical purpose.
+- Calendar notes can set their own display formats, and being birth and death dates receive date validation.
+- Structured place and affiliation relationships appear as linked rows in the infobox.
+
+**Published output**
+
+- Content indexes identify each system's Actor document separately when a note produces more than one.
+- Alternative art builds report image names that have no matching note in the related package.
+- Site search archives include every indexed page.
+
 ## 22.14.2
 
 ### Patch Changes

package/bin/content-build.mjs

@@ -24,7 +24,7 @@
  *
  * The side effects that need *configuration* live inside the command handler,
  * not at module scope, so `--version` and `--help` answer in a directory that
- * has neither a `package-build.config.yaml` nor a package manifest (#2).
+ * has neither a `package-build.config.yaml` nor a package manifest.
  * Running an actual command still resolves both, and still fails loudly when
  * either is missing.
  *
@@ -158,11 +158,11 @@ import { loadMapWorld } from "../engine/map-places.mjs";
  * knows them. It does not come out of the shipped manifest — a second
  * declaration of the same list, in a second format, with nothing checking that
  * the two agreed. The manifest is generated from this list now
- * (package-build#9), so reading it back would be a round trip through an
+ *, so reading it back would be a round trip through an
  * artifact that need not exist.
  *
  * Read on demand rather than at load, so `--version` and `--help` still answer
- * with no configuration present (#2).
+ * with no configuration present.
  *
  * @returns {Array<{name: string}>}
  */
@@ -1979,8 +1979,8 @@ function reachabilityCommand() {
  */
 async function fetchFromLocalArtifact(config, argv) {
     // Two caches, two dependency sets: an index is fetched for every declared
-    // dependency, a catalogue only for those declaring `itemCatalog: true`
-    // (#239). `--from` fills whichever of them this dependency belongs to, so
+    // dependency, a catalogue only for those declaring `itemCatalog: true`.
+    // `--from` fills whichever of them this dependency belongs to, so
     // that testing against an unreleased build behaves like a release would.
     const rels = metadataRelationships(config);
     const named = rels.map((r) => r.id).join(", ") || "none";
@@ -2307,7 +2307,7 @@ function packageCommand() {
                 // The one directory the pipeline creates rather than expects:
                 // `unpack` writes the extracted JSON there and `compile` reads
                 // it back. Created here rather than at module scope so that
-                // asking the CLI its version needs no configuration (#2).
+                // asking the CLI its version needs no configuration.
                 fs.mkdirSync(config.paths.unpack, {
                     recursive: true,
                 });

package/bin/package-build.mjs

@@ -80,6 +80,8 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
+import { checkForeignAssetBindings } from "../engine/asset-bindings.mjs";
+import { formatDiagnostic } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
@@ -271,6 +273,14 @@ function assetsCommand() {
                 console.log("package-build: no `packageBuild.assets` declared; nothing to stage.");
                 return;
             }
+            const bindings = checkForeignAssetBindings(loadPackConfig(), {
+                assets: config.assets,
+            });
+            if (bindings.length) {
+                const error = new Error(bindings.map(formatDiagnostic).join("\n"));
+                error.located = true;
+                die(error);
+            }
 
             let transform;
             if (config.assetTransform) {

package/config.mjs

@@ -100,7 +100,7 @@ export const DERIVED_MANIFEST_KEYS = Object.freeze({
     relationships: "the top level of package-build.config.yaml",
     packs: "the `packs` list at the top level of package-build.config.yaml",
 });
-const ASSET_KEYS = ["from", "to"];
+const ASSET_KEYS = ["from", "to", "bindsTo"];
 const CLEAN_KEYS = ["extra"];
 const LANG_KEYS = [
     "sources",
@@ -210,6 +210,8 @@ function requireNonEmptyString(value, where) {
  * @typedef {object} AssetSpec
  * @property {string} from  Source path, relative to the repository root.
  * @property {string} to    Destination, relative to the staged package root.
+ * @property {{package: string, system: string, type: string}|undefined} [bindsTo]
+ *   The foreign Address each file's basename claims, without its shortcode.
  */
 
 /**
@@ -222,9 +224,24 @@ function normalizeAsset(value, index) {
     if (!isMapping(value)) fail(where, "must be a mapping");
     const asset = /** @type {Record<string, unknown>} */ (value);
     rejectUnknownKeys(asset, ASSET_KEYS, `${where}.`);
+    let bindsTo;
+    if (asset.bindsTo !== undefined) {
+        if (!isMapping(asset.bindsTo)) fail(`${where}.bindsTo`, "must be a mapping");
+        const binding = /** @type {Record<string, unknown>} */ (asset.bindsTo);
+        rejectUnknownKeys(binding, ["package", "system", "type"], `${where}.bindsTo.`);
+        bindsTo = Object.freeze({
+            package: requireNonEmptyString(binding.package, `${where}.bindsTo.package`),
+            system:
+                binding.system === undefined ?
+                    "note"
+                :   requireNonEmptyString(binding.system, `${where}.bindsTo.system`),
+            type: requireNonEmptyString(binding.type, `${where}.bindsTo.type`),
+        });
+    }
     return Object.freeze({
         from: requireNonEmptyString(asset.from, `${where}.from`),
         to: requireNonEmptyString(asset.to, `${where}.to`),
+        ...(bindsTo ? { bindsTo } : {}),
     });
 }
 

package/content-config.mjs

@@ -688,7 +688,7 @@ export function publishesContentPages(config) {
  * @property {Readonly<Record<string, string>>} itemArt  Derived: the default art
  *                                     of each entry that paired one. Sparse — a
  *                                     type absent here has no default, and a note
- *                                     of it must carry `img:` (#7).
+ *                                     of it must carry `img:`.
  * @property {Readonly<Record<string, readonly object[]>>} itemFields  Derived:
  *                                     the frontmatter fields each entry
  *                                     declared. Sparse, like `itemArt` — a type
@@ -2202,7 +2202,7 @@ function normalizePackageBuild(value) {
  * travel by different routes: `itemTypes` was derived from these keys, while
  * art was looked up in `sohl/default-item-art.mjs` — a table a consumer cannot
  * add to. A consumer's own item type was therefore configurable while its
- * default art was not, so its notes all had to carry an explicit `img:` (#7).
+ * default art was not, so its notes all had to carry an explicit `img:`.
  * Art now travels with the builder it belongs to, which is the one place a type
  * is already declared.
  *

package/docs/api.md

@@ -5,15 +5,11 @@ subpath entries, declared in `package.json`'s `exports` map. Every function
 and value documented here is a supported contract, not an internal seam —
 `./sohl` and `./hm3` included.
 
-**Everything exported anywhere in this package is pure.** A function takes
-source text or already-loaded data and returns findings or values;
-discovery, I/O and reporting stay with the caller. That is what lets one
-rule set serve a lint script, a build step and a unit test without any of
-them having to agree on how files are found or how findings are printed. A
-handful of packaging functions — deploying, staging, running a container,
-packing a release — necessarily touch the filesystem or a subprocess; each
-is named for it in the tables below, and the pure half of its module is kept
-separate from it.
+Rule functions take source text or already-loaded data and return findings or
+values. That lets one rule set serve a lint script, a build step and a unit
+test without tying diagnostics to a particular reporter. Context builders,
+content walks, site rendering, and packaging functions read or write files as
+their signatures and descriptions state.
 
 This reference is organized by subpath entry, matching how a consumer
 imports: `import * as engine from "@heroiclands/package-build/engine"` reads
@@ -640,19 +636,22 @@ A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<calendar sho
 
 A calendar is a `lore` note with `subType: calendar`, declaring the months it keeps, the weekdays it names, the seasons it marks and the eras it counts years in. How long the year is, how the day divides and how the moon moves are facts about the **world**, written on its `place` note and its moon's, and no calendar may restate them — which is why the months summing to the world's year is the only arithmetic a calendar note is held to. One definition is emitted per calendar, in array shape: Foundry core prunes the keys outside its schema, and Calendaria converts the arrays to its own keyed collections.
 
-| Export               | Signature                                             | Returns                                    | Use it when                                                                 |
-| -------------------- | ----------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
-| `CALENDAR_SUBTYPE`   | `const CALENDAR_SUBTYPE`                              | —                                          | naming the `lore` subType whose notes are calendars                         |
-| `INVARIANT_SUBTYPES` | `const INVARIANT_SUBTYPES`                            | —                                          | naming the `place` subTypes a world fact may be written on                  |
-| `CALENDAR_FIELDS`    | `const CALENDAR_FIELDS`                               | —                                          | reading the closed list of what a calendar note may declare                 |
-| `INVARIANT_FIELDS`   | `const INVARIANT_FIELDS`                              | —                                          | reading the closed list of what a body may declare about itself             |
-| `checkCalendarNote`  | `checkCalendarNote(note, opts)`                       | `object[]` — findings                      | holding a `lore` note to the family and to the year the world keeps         |
-| `checkWorldFacts`    | `checkWorldFacts(note, opts)`                         | `object[]` — findings                      | holding a `place` note's world facts to one body, one year and one moon     |
-| `worldInvariants`    | `worldInvariants(index)`                              | `{year, present, moon, body, moonName, …}` | reading the year, the present and the moon a package's own notes state      |
-| `quarterDays`        | `quarterDays(daysPerYear)`                            | `number[]` — four days of the year         | asking which days the year turns on                                         |
-| `compileCalendar`    | `compileCalendar({note, invariants, contentPackage})` | `object` — the definition                  | building the one object both a core consumer and Calendaria read            |
-| `compileCalendars`   | `compileCalendars(index, opts)`                       | `{calendars, invariants}`                  | building every calendar a package declares, or none where it states no year |
-| `calendariaEnvelope` | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope             | wrapping a definition for a hand import through Calendaria's settings       |
+| Export                      | Signature                                             | Returns                                    | Use it when                                                                 |
+| --------------------------- | ----------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
+| `CALENDAR_SUBTYPE`          | `const CALENDAR_SUBTYPE`                              | —                                          | naming the `lore` subType whose notes are calendars                         |
+| `INVARIANT_SUBTYPES`        | `const INVARIANT_SUBTYPES`                            | —                                          | naming the `place` subTypes a world fact may be written on                  |
+| `CALENDAR_FIELDS`           | `const CALENDAR_FIELDS`                               | —                                          | reading the closed list of what a calendar note may declare                 |
+| `CALENDAR_DATE_FORMAT_KEYS` | `const CALENDAR_DATE_FORMAT_KEYS`                     | —                                          | reading the supported Calendaria display slots                              |
+| `CALENDAR_FORMAT_TOKENS`    | `const CALENDAR_FORMAT_TOKENS`                        | —                                          | checking bare date tokens in a format string                                |
+| `INVARIANT_FIELDS`          | `const INVARIANT_FIELDS`                              | —                                          | reading the closed list of what a body may declare about itself             |
+| `checkCalendarNote`         | `checkCalendarNote(note, opts)`                       | `object[]` — findings                      | holding a `lore` note to the family and to the year the world keeps         |
+| `checkCalendarDateFormats`  | `checkCalendarDateFormats(note)`                      | `object[]` — findings                      | checking display slots and escaped literal words                            |
+| `checkWorldFacts`           | `checkWorldFacts(note, opts)`                         | `object[]` — findings                      | holding a `place` note's world facts to one body, one year and one moon     |
+| `worldInvariants`           | `worldInvariants(index)`                              | `{year, present, moon, body, moonName, …}` | reading the year, the present and the moon a package's own notes state      |
+| `quarterDays`               | `quarterDays(daysPerYear)`                            | `number[]` — four days of the year         | asking which days the year turns on                                         |
+| `compileCalendar`           | `compileCalendar({note, invariants, contentPackage})` | `object` — the definition                  | building the one object both a core consumer and Calendaria read            |
+| `compileCalendars`          | `compileCalendars(index, opts)`                       | `{calendars, invariants}`                  | building every calendar a package declares, or none where it states no year |
+| `calendariaEnvelope`        | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope             | wrapping a definition for a hand import through Calendaria's settings       |
 
 ### `engine.beingAge`
 
@@ -769,17 +768,18 @@ 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, 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 |
+| 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.                                                                                                                                                           |
+| `indexRecordsForNote`   | `indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext })` | `object[]`                                                                                                                                                                                                                                                                  | Derive the note's own record and its documentation record from parsed text.                                                                                                                                               |
+| `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 eight names from neighbouring leaf modules, at this same import path:
 
@@ -860,10 +860,38 @@ Publishing a content tree as a website. Compiling a content tree into compendium
 | `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.                                                          |
 | `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                                                                |
 | `pageDestination`     | `function pageDestination(page, { bundle })`      | —                                                                                                                                      | Where a page is written, relative to the output root: flat, or as a leaf bundle when it carries a file beside itself. |
+| `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, locate })`        | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
 
+### `engine.sitePreview`
+
+`prepareSitePreview({ config })` reads the saved content tree and declared dependency indexes, prepares its SQL corpus, and returns a private preview context. Pass the active note's absolute path and complete buffer text to `render(file, text)`. A successful result has `{ ok: true, markdown, frontmatter, findings: [] }`; a failed result has `{ ok: false, findings }` and no replacement content. Findings identify the source file and carry a line and column when the offending text can be located.
+
+| Export               | Signature                        | Returns                                    | Use it when                                        |
+| -------------------- | -------------------------------- | ------------------------------------------ | -------------------------------------------------- |
+| `prepareSitePreview` | `prepareSitePreview({ config })` | `{render(file, text), refresh(), close()}` | An editor needs a private, reusable page renderer. |
+
+The context keeps other notes and foreign packages at their saved state. Call `refresh()` after a save to read them again, and `close()` when the editor releases the project. Rendering and refreshing never write the authored notes or the site's `build/hugo/content` mount. The editor owns any private HTML artifact and keeps its last complete artifact when a render fails.
+
+```js
+import { sitePreview } from "@heroiclands/package-build/engine";
+
+const preview = await sitePreview.prepareSitePreview({ config });
+try {
+  const result = await preview.render(absoluteFile, currentBufferText);
+  if (result.ok) {
+    // Convert result.markdown and result.frontmatter to the editor's HTML preview.
+  } else {
+    showDiagnostics(result.findings);
+  }
+} finally {
+  await preview.close();
+}
+```
+
 ### `engine.contentLint`
 
 Linting a content tree's **addresses** — the rules every package's notes are authored against, wherever those notes live. These rules do not live in a consumer's `utils/`, which has two consequences and no upside. `thalorna` and `kethira` notes were checked by nothing at all, so the packages most likely to carry authoring mistakes were the ones nothing inspected. And one rule with two implementations can disagree without anything detecting it, which the canonical-separator handling already did once on each side.
@@ -996,7 +1024,7 @@ Wikilink resolution for the knowledgebase build. The same authored links the pac
 
 ### `engine.contentTables`
 
-Generated content tables — Obsidian **Dataview** `TABLE` queries. A catalog table (every cloth armour, every animal's abilities) is data that already lives in the frontmatter of the notes it describes. Authoring such a table by hand duplicates that data and guarantees drift, so a content body instead declares what it wants tabulated, in a fenced `dataview` block:
+Generated content tables from fenced `dataview` `TABLE` queries. A catalog table (every cloth armour, every animal's abilities) is data that already lives in the frontmatter of the notes it describes. Authoring such a table by hand duplicates that data and guarantees drift, so a content body instead declares what it wants tabulated, in a fenced `dataview` block:
 
 | Export                | Signature                                                                    | Returns                                                                                                                                                            | Use it when                                                                                                                                                                                                                 |
 | --------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1116,7 +1144,7 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 
 ### `engine.pdfToc`
 
-The document tree a PDF is built from, and the plan it resolves to (#316). The packs and the website both render the _whole_ content tree: every note becomes a document and a page, and the three surfaces agreeing about what the content is, is the point. **A book is not that.** It is a selection — a declared structure whose leaves pick notes out of the corpus by a `WHERE` clause, interleaved with prose that may not live in the content tree at all.
+The document tree a PDF is built from, and the plan it resolves to. The packs and the website both render the _whole_ content tree: every note becomes a document and a page, and the three surfaces agreeing about what the content is, is the point. **A book is not that.** It is a selection — a declared structure whose leaves pick notes out of the corpus by a `WHERE` clause, interleaved with prose that may not live in the content tree at all.
 
 | Export              | Signature                                  | Returns                                                                                                                                                              | Use it when                                                        |
 | ------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |

package/docs/configuration.md

@@ -529,8 +529,8 @@ Any other key is refused:
 
 **Type:** string[] · **Optional** · default `[]`.
 
-Directory names the content walk ignores wherever they appear — Obsidian's
-`Templates`, for instance.
+Directory names the content walk ignores wherever they appear — an author's
+`Templates` directory, for instance.
 
 ```yaml
 skipDirectories: [Templates]
@@ -1465,10 +1465,11 @@ table says `lang`, not `build/stage/lang`.
 `assets` is the table of staging copies: source path in the repository,
 destination under the staged package root.
 
-| Key                          | Type   | Required |
-| ---------------------------- | ------ | -------- |
-| `packageBuild.assets[].from` | string | yes      |
-| `packageBuild.assets[].to`   | string | yes      |
+| Key                             | Type                       | Required |
+| ------------------------------- | -------------------------- | -------- |
+| `packageBuild.assets[].from`    | string                     | yes      |
+| `packageBuild.assets[].to`      | string                     | yes      |
+| `packageBuild.assets[].bindsTo` | `{package, type, system?}` | no       |
 
 > ``package-build config: `packageBuild.stageDir` must be a non-empty string.``
 
@@ -1478,7 +1479,15 @@ destination under the staged package root.
 
 > ``package-build config: `packageBuild.assets[<index>].from` must be a non-empty string.``
 
-> ``package-build config: `packageBuild.assets[<index>].<key>` is not a recognised key (expected one of: from, to).``
+> ``package-build config: `packageBuild.assets[<index>].<key>` is not a recognised key (expected one of: from, to, bindsTo).``
+
+`bindsTo` says that every file under this copy's `from` directory uses its
+filename, without the extension, as a foreign Address shortcode. `package`
+and `type` are required; `system` defaults to `note`. The relationship with
+that package must provide a content index for the build to check the binding.
+The check reads the cached index, reports an unresolved file as an error, and
+does not fetch during compilation. Run `content-build deps fetch` to fill a
+cold cache.
 
 ### `packageBuild.assetTransform` and `packageBuild.manifestFlags`