@heroiclands/package-build 22.12.3 → 22.13.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @heroiclands/package-build
 
+## 22.13.1
+
+### Patch Changes
+
+Content authors can keep pinned document identities and compendium placement alongside shared note facts.
+
+## 22.13.0
+
+### Minor Changes
+
+**Content links**
+
+- Ordinary wikilinks open readable notes by default; image embeds and art fields resolve systemless assets.
+- Readable notes use `note` addresses, while explicit game systems select Actors and Items and `none` selects systemless targets.
+
+**Editor navigation**
+
+- Install `@heroiclands/content-language-server` for content note search and navigation in an editor.
+
 ## 22.12.3
 
 ### Patch Changes

package/README.md

@@ -14,8 +14,8 @@ The content half is documented separately in **[CONTENT.md](CONTENT.md)** — th
 note format, the pack pipeline, and the configuration contract a content tree
 declares itself with.
 
-Editor navigation through the content index is described in the
-[content language server guide](docs/content-language-server.md).
+Editor navigation for content projects is provided by
+[`@heroiclands/content-language-server`](https://github.com/HeroicLands/content-language-server).
 
 ## Install
 

package/docs/api.md

@@ -119,28 +119,29 @@ Deterministic document ids, derived by hashing rather than stored, so compile pa
 
 The per-system frontmatter block: how one note feeds more than one game system through properties named after that system (`<system>.system`, `<system>.type`, `<system>.img`, `<system>.items` on actors). Resolves a field's value through the block, the shared top level, and a retiring position in that order, and merges an authored `<system>.system` onto a compiler-built one without disturbing what the builder already wrote.
 
-| Export                      | Signature                                     | Returns                                | Use it when                                                                                   |
-| --------------------------- | --------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                       | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
-| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`             | —                                      | mapping a system-block key to the document property it becomes                                |
-| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                      | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
-| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                     | —                                      | enumerating every key any system block may carry                                              |
-| `setPath`                   | `setPath(target, dotted, value)`              | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
-| `systemBlock`               | `systemBlock(fm, block)`                      | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
-| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`               | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
-| `systemData`                | `systemData(fm, block)`                       | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
-| `blockField`                | `blockField(fm, block, key, defaultValue)`    | the value                              | reading a key from one system's block, falling back to the top level                          |
-| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`    | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
-| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)` | the value                              | reading a property a system block may override, else the shared top-level one                 |
-| `legacyKeyOf`               | `legacyKeyOf(field)`                          | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
-| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                   | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
-| `authoredKey`               | `authoredKey(name)`                           | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
-| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`           | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
-| `systemDataPaths`           | `systemDataPaths(data, prefix)`               | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
-| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`     | `string[]`                             | finding authored paths a system's published schema does not declare                           |
-| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`            | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
-| `claimedPaths`              | `claimedPaths(fields)`                        | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
-| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`             | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
+| Export                      | Signature                                         | Returns                                | Use it when                                                                                   |
+| --------------------------- | ------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                           | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
+| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                 | —                                      | mapping a system-block key to the document property it becomes                                |
+| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                          | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
+| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                         | —                                      | enumerating every key any system block may carry                                              |
+| `setPath`                   | `setPath(target, dotted, value)`                  | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
+| `systemBlock`               | `systemBlock(fm, block)`                          | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
+| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                   | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
+| `systemData`                | `systemData(fm, block)`                           | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
+| `blockField`                | `blockField(fm, block, key, defaultValue)`        | the value                              | reading a key from one system's block, falling back to the top level                          |
+| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`        | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
+| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`     | the value                              | reading a property a system block may override, else the shared top-level one                 |
+| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)` | the value                              | reading a system override, then shared `data`, then a top-level value                         |
+| `legacyKeyOf`               | `legacyKeyOf(field)`                              | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
+| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                       | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
+| `authoredKey`               | `authoredKey(name)`                               | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
+| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`               | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
+| `systemDataPaths`           | `systemDataPaths(data, prefix)`                   | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
+| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`         | `string[]`                             | finding authored paths a system's published schema does not declare                           |
+| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
+| `claimedPaths`              | `claimedPaths(fields)`                            | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
+| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                 | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
 
 ### `engine.codeFences`
 
@@ -596,16 +597,17 @@ The map from each place, drawn for the site: `content-build site` draws the map
 
 The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.
 
-| Export                 | Signature                              | Returns                         | Use it when                                                                                  |
-| ---------------------- | -------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- |
-| `NO_SYSTEM`            | `const NO_SYSTEM`                      | —                               | naming the `<system>` segment of a note that belongs to no game system                       |
-| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating every game system this toolchain compiles for                                    |
-| `SYSTEM_SEGMENTS`      | `const SYSTEM_SEGMENTS`                | —                               | enumerating everything the `<system>` address segment may say — the systems plus `NO_SYSTEM` |
-| `isSystemId`           | `isSystemId(value)`                    | `boolean`                       | checking whether a value names a game system this toolchain knows (`none` is rejected)       |
-| `isSystemSegment`      | `isSystemSegment(value)`               | `boolean`                       | checking whether a value is something the `<system>` address segment may hold                |
-| `unknownSystemMessage` | `unknownSystemMessage(value, where)`   | `string`                        | building the message for a caller that wrote an unknown system                               |
-| `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                      |
-| `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment                     |
+| Export                 | Signature                              | Returns                         | Use it when                                                                            |
+| ---------------------- | -------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| `NO_SYSTEM`            | `const NO_SYSTEM`                      | —                               | naming a systemless asset or Foundry document                                          |
+| `NOTE_SYSTEM`          | `const NOTE_SYSTEM`                    | —                               | naming readable note content across web, book and Foundry                              |
+| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating every game system this toolchain compiles for                              |
+| `SYSTEM_SEGMENTS`      | `const SYSTEM_SEGMENTS`                | —                               | enumerating the game systems, `note` and `none`                                        |
+| `isSystemId`           | `isSystemId(value)`                    | `boolean`                       | checking whether a value names a game system this toolchain knows (`none` is rejected) |
+| `isSystemSegment`      | `isSystemSegment(value)`               | `boolean`                       | checking whether a value is something the `<system>` address segment may hold          |
+| `unknownSystemMessage` | `unknownSystemMessage(value, where)`   | `string`                        | building the message for a caller that wrote an unknown system                         |
+| `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                |
+| `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment               |
 
 ### `engine.calendars`
 
@@ -675,7 +677,7 @@ Where a content note publishes on the web. One rule, in one place, because two b
 | `addressSlug`            | `function addressSlug(fm)`                            | {string} The address segment, e.g.                                                                                                                                                                      | The single path segment a note is addressed by: `type-shortcode`.                                     |
 | `packageAddress`         | `function packageAddress(fm)`                         | {string} The package-relative address, with a trailing slash and no leading one.                                                                                                                        | A note's address: `<type>-<shortcode>/`, e.g.                                                         |
 | `canonicalKey`           | `function canonicalKey(pkg, system, type, shortcode)` | {string} `package-system-type-shortcode`, lowercased.                                                                                                                                                   | The **canonical** address of a note: fully qualified, one spelling per document, and globally unique. |
-| `blockSystem`            | `function blockSystem(keyPath)`                       | {string} The system id, or `none`.                                                                                                                                                                      | Which system a frontmatter key path is written under.                                                 |
+| `blockSystem`            | `function blockSystem(keyPath)`                       | {string} The game system id, or `note`.                                                                                                                                                                 | Which system a frontmatter key path is written under.                                                 |
 | `expandAddress`          | `function expandAddress(read, where)`                 | {string} The canonical `package-system-type-shortcode`.                                                                                                                                                 | Expand a written address to the one canonical address it names.                                       |
 | `CANONICAL_KEY_SEGMENTS` | `const CANONICAL_KEY_SEGMENTS`                        | —                                                                                                                                                                                                       | How many segments a canonical key has, and therefore how many the reader below counts.                |
 | `readCanonicalKey`       | `function readCanonicalKey(key)`                      | {{package: string, system: string, type: string, shortcode: string} \|null\|undefined} The parts; `null` when there is a string that is not in canonical form; `undefined` when there is no key at all. | Reads a canonical key back into its parts.                                                            |
@@ -1062,12 +1064,12 @@ Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLa
 
 **Item docs** — an item's prose compiled as a JournalEntry, with the item keeping only a pointer to it. An item note's body describes what the thing _is_. That is documentation, and documentation belongs in the journals pack, so each item note compiles into a JournalEntry and the item's `system.docHtml` becomes nothing but a `@UUID` link to that entry's first page — the description-as-pointer convention, which {@link sohl.utils.descriptionLinkTarget} recognises and Display Description follows.
 
-| Export           | Signature                                                       | Returns                                                                                          | Use it when                                                                                                                 |
-| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| `docEntryTypes`  | `function docEntryTypes()`                                      | {ReadonlySet<string>} The configured doc-carrying types.                                         | Every content type whose **prose compiles into a JournalEntry of its own**, addressed by the virtual `doc<type>` qualifier. |
-| `hasDocEntry`    | `function hasDocEntry(type)`                                    | {boolean} True for an item type, for `macro` and for a map type; false for `doc` and for actors. | Whether a content note's type is one whose prose becomes a JournalEntry of its own.                                         |
-| `itemDocEntryId` | `function itemDocEntryId(itemId)`                               | {string} A 16-character Foundry id.                                                              | The id of the JournalEntry a note's prose compiles into — an item's, or a macro's.                                          |
-| `itemDocPointer` | `function itemDocPointer(packageId, itemId, name, firstPageId)` | {string} The pointer to store in `system.docHtml`.                                               | The description an item carries in place of its prose: a `@UUID` link to the first page of its item doc, and nothing else.  |
+| Export           | Signature                                                       | Returns                                                                                          | Use it when                                                                                                                |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `docEntryTypes`  | `function docEntryTypes()`                                      | {ReadonlySet<string>} The configured doc-carrying types.                                         | Every content type whose **prose compiles into a JournalEntry of its own**, addressed by `note` with the authored type.    |
+| `hasDocEntry`    | `function hasDocEntry(type)`                                    | {boolean} True for an item type, for `macro` and for a map type; false for `doc` and for actors. | Whether a content note's type is one whose prose becomes a JournalEntry of its own.                                        |
+| `itemDocEntryId` | `function itemDocEntryId(itemId)`                               | {string} A 16-character Foundry id.                                                              | The id of the JournalEntry a note's prose compiles into — an item's, or a macro's.                                         |
+| `itemDocPointer` | `function itemDocPointer(packageId, itemId, name, firstPageId)` | {string} The pointer to store in `system.docHtml`.                                               | The description an item carries in place of its prose: a `@UUID` link to the first page of its item doc, and nothing else. |
 
 - `itemTypes` — re-exported: Every content type that compiles into an item — and therefore into an item doc.
 
@@ -1077,7 +1079,7 @@ Wikilink resolution for the pack compilers. Content notes link to one another wi
 
 | 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 a qualifier as the **virtual `doc<type>`** form, or reports that it is not one.                                                                                      |
+| `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.                                                                                                                      |

package/docs/commands.md

@@ -6,9 +6,6 @@ container, drive the end-to-end suite. `content-build` is the content half —
 compile a note tree into compendium packs, check it, publish it as a site or a
 book, and manage the caches a build resolves other packages through.
 
-The package also ships `heroiclands-content-language-server`, a stdio editor
-service described in the [content language server guide](content-language-server.md).
-
 Both read `package-build.config.yaml` from the repository root — see
 [Configuration](configuration.md) for every key. Neither reads it for
 `--version` or `--help`: those two answer in a directory with no

package/docs/content-format.md

@@ -96,7 +96,7 @@ column regardless.
 
 **Embedded models link to documentation in an infobox.** The model Address
 continues to identify the native Item used for compilation. Its displayed link
-uses that same package, type and Shortcode under `none`, which names the
+uses that same package, type and Shortcode under `note`, which names the
 corresponding documentation journal. A model with no published documentation
 keeps its known name as plain text; the infobox does not substitute an Actor or
 Item link.
@@ -308,6 +308,12 @@ finding that names the key you meant; the same misspelling at top level would
 silently become a theme parameter, which is exactly why these cannot live
 together.
 
+Every note type may put a pinned document id in `data.id`, a shared compendium
+route in `data.pack`, a shared folder Address in `data.packFolder`, and source
+details in `data.harnworld`. A system block's `pack` or `packFolder` overrides
+the shared value for that system. A `being` may also describe its social profile
+in `data.social`.
+
 **Tags are open, except the ones that classify.** `tags:` shares the top level's
 openness: a tag naming a theme or a region — `underworld`,
 `byzaria`, `riverlands` — is the author's own and this build has no opinion about it.
@@ -569,8 +575,8 @@ type.
 | ----------------------- | ------------------------- | ---------------------------- |
 | `name.full`             | `name`                    | `name`                       |
 | `data.icon`             | `img`                     | `img`                        |
-| `id`                    | `_id`                     | `_id`                        |
-| `packFolder`            | `folder`                  | `folder`                     |
+| `data.id`               | `_id`                     | `_id`                        |
+| `data.packFolder`       | `folder`                  | `folder`                     |
 | `shortcode`             | `system.shortcode`        | NA                           |
 | `data.templatePriority` | `system.templatePriority` | `flags.hm3.templatePriority` |
 | `actionDefs`            | `system.actionDefs`       | NA                           |
@@ -657,16 +663,20 @@ refused at all four slots: a sound is not art, and a value naming one — `icon:
 audio-thunder`, say — is an error naming the set the slot accepts, never a
 silent fall back to the note's default art.
 
-**Two of them are legal on _every_ note**, whatever its type. `data:` is a
+**These properties are legal on _every_ note**, whatever its type. `data:` is a
 closed container and the per-type vocabularies below are the only lists there
 are, so a key legal everywhere is stated once here rather than repeated in
 twenty-five tables where the one that was mistyped would be the one nobody
 noticed:
 
-| shared `data` property | Values    | Description                                                          |
-| ---------------------- | --------- | -------------------------------------------------------------------- |
-| `icon`                 | `Address` | The document's profile art — an `icon` address, resolved into `img`. |
-| `banner`               | `Address` | The page's hero image — an `image` address.                          |
+| shared `data` property | Values                 | Description                                                          |
+| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `id`                   | `string`               | A pinned document identity.                                          |
+| `pack`                 | `string`               | The shared compendium route.                                         |
+| `packFolder`           | `Address` or pack map  | The shared compendium folder Address.                                |
+| `harnworld`            | `Map<string, unknown>` | HârnWorld source details.                                            |
+| `icon`                 | `Address`              | The document's profile art — an `icon` address, resolved into `img`. |
+| `banner`               | `Address`              | The page's hero image — an `image` address.                          |
 
 `icon` is legal everywhere because most types compile into a document that
 carries one; where a type's passes emit none, the lint says so and the value is
@@ -847,10 +857,11 @@ on any type, and the frontmatter lint never reports it.
 
 #### The pack a note compiles into
 
-`pack` names which configured compendium receives the note's document.
+`data.pack` names which configured compendium receives the note's document.
 
 ```yaml
-pack: items-hm3
+data:
+  pack: items-hm3
 ```
 
 It is deliberately close to the retired `package:` and deliberately not the same
@@ -867,7 +878,8 @@ system: each block the note carries sends its own document where that block
 says, and a note carrying two blocks may place them in two packs.
 
 ```yaml
-pack: items-sohl
+data:
+  pack: items-sohl
 hm3:
   pack: items-hm3
 ```
@@ -898,10 +910,11 @@ and in no compendium — a page of developer documentation, a page about the
 package itself:
 
 ```yaml
+shortcode: architecture
 type: doc
 subType: concept
-shortcode: architecture
-pack: none
+data:
+  pack: none
 ```
 
 A link to such a note resolves everywhere the note is addressable. On the web
@@ -1046,16 +1059,17 @@ none. It is the same principle that turned `folder: ONXsqZAIZr2qzxTb` into
 `packFolder: <address>` above: an opaque derived identity does not belong in
 authored content.
 
-**An authored `id` still wins**, and that is how a document's identity is
+**An authored `data.id` wins**, and that is how a document's identity is
 **pinned**:
 
 ```yaml
-type: miscgear
 shortcode: bowlcer
-id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
+type: miscgear
+data:
+  id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
 ```
 
-A blank `id:` is not a pin — it is a deleted value with the key left behind, and
+A blank `data.id:` is not a pin — it is a deleted value with the key left behind, and
 is treated as absent.
 
 **A rename moves the id, and that is the trade.** The address carries the
@@ -1144,7 +1158,8 @@ of the same entry is a warning; the declaration still works.
 A note says which folder of its pack it lands in:
 
 ```yaml
-packFolder: poisonsandtoxins # a folder note's address
+data:
+  packFolder: poisonsandtoxins # a folder note's address
 ```
 
 **`packFolder` is a folder note's address** — an ordinary address, resolved the
@@ -1268,85 +1283,78 @@ below.
 <package>-<system>-<note_type>-<shortcode>
 ```
 
-Read it from the right: the last segment is always the shortcode, the one before
-it always the note type, the one before that always the system, and the first the
-package. Nothing is positional-by-guess — a segment means what its position says
-it means.
+The final segment is the shortcode, preceded by the note type, the system and
+the package. Each segment has one position. The system says which kind of target
+is named:
 
-The `<system>` segment is `none` for a note that belongs to no system, which is
-most of them: `harnadventures-none-being-grod`. A note that exists only for one
-system names it.
+| system        | target                                                                      |
+| ------------- | --------------------------------------------------------------------------- |
+| `note`        | Readable note content: a web page, a book entry, or a Foundry JournalEntry. |
+| `none`        | A systemless target such as an asset, Folder, Macro or Scene.               |
+| `sohl`, `hm3` | A game system's Actor or Item document.                                     |
+
+A note can publish more than one Address. A `being` note, for example, publishes
+`thalorna-note-being-bctrncml` for its readable content and
+`thalorna-sohl-being-bctrncml` for its SoHL Actor. An item note follows the same
+pattern for its page and Item. The type segment remains the authored note type
+in each Address.
 
 #### Shorter forms
 
-The full address is the unambiguous form, and almost nothing uses it — 92 of
-12,056 links in the current trees. The rest rely on shorter forms, each dropping
-segments from the left:
+Authors may omit segments from the left. The complete Address states all four:
 
 | form                            | expands to                                               |
 | ------------------------------- | -------------------------------------------------------- |
 | `package-system-type-shortcode` | itself                                                   |
 | `system-type-shortcode`         | `<this package>-system-type-shortcode`                   |
-| `type-shortcode`                | `<this package>-<this block's system>-type-shortcode`    |
-| `shortcode`                     | as above, with the type from the field's own declaration |
+| `type-shortcode`                | `<this package>-<this position's system>-type-shortcode` |
+| `shortcode`                     | as above, with the type from the field's declaration     |
 
-There is no `package-type-shortcode`: the forms are exactly the **suffixes** of
-the canonical address, so naming another package means naming its system too.
-`kethira-place-tashal` is three segments, which reads as system `kethira`, and
-fails.
+There is no `package-type-shortcode` form. A reference to another package states
+its system as well as its package.
 
 #### Authored references and generated references
 
-Authored notes may use any permitted suffix. Builds leave those source bytes
-unchanged. Generated content indexes, SQL records, site frontmatter and generated
-Wikilinks contain full `package-system-type-shortcode` Addresses. For example,
-`data.parents: [north]` in the `thalorna` package emits
-`data.parents: [thalorna-none-place-north]`.
+Authored notes may use any permitted suffix. Builds leave source bytes unchanged.
+Generated content indexes, SQL records, site frontmatter and generated
+Wikilinks contain complete Addresses. For example, `data.parents: [north]` in
+`thalorna` emits `data.parents: [thalorna-note-place-north]`.
 
-SQL queries compare Address-valued fields to full Addresses. A note's `shortcode`
-is a distinct identity component, so it is not equal to an Address stored in
-`data.parents`, `data.domains` or a governance rank's `lore`. Use the target's
-complete identity for that comparison, including its package, system and type.
-A stub has no published page address; its note identity still contains those
-components and its Shortcode.
+SQL queries compare Address-valued fields to complete Addresses. A note's
+`shortcode` is a distinct identity component, so it is not equal to an Address
+stored in `data.parents`, `data.domains` or a governance rank's `lore`. Use the
+target's complete identity for that comparison. A stub has no published page
+address; its note identity still contains the package, system, type and shortcode.
 
-The toolchain holds parsed Address properties as complete tuples internally.
-Address-keyed relation maps hold typed targets and standing values. Only generated
-output serializes these properties to Address strings. Runtime Shortcodes,
-Foundry UUIDs, file paths and URLs keep their own representations.
+The toolchain holds parsed Addresses as complete tuples internally. Address-keyed
+relation maps hold typed targets and standing values. Only generated output
+serializes these properties to Address strings. Runtime Shortcodes, Foundry
+UUIDs, file paths and URLs keep their own representations.
 
 An Address-valued `data:` field must name a target in this package or a declared
-dependency index. `content-build lint` reports a missing target as an error at
-the value or map key that names it. A stub counts as a target for data even
-though it publishes no page. Art slots use their own missing-art warning and
-document fallback.
+dependency index. `content-build lint` reports a missing target at the value or
+map key that names it. A stub counts as a target for data even though it
+publishes no page. Art slots use their own missing-art warning and document
+fallback.
 
 #### An omitted segment defaults from where the link is written
 
-It is **not** a wildcard and resolution is not a search. Every short form expands
-to exactly one canonical address before anything is looked up, so a lookup either
-finds one entry or none — there is no candidate set, and a cross-package
-ambiguity is impossible by construction.
-
-- **package** omitted → the current package. A short address therefore names
-  _this_ package and never falls through to a dependency; reaching another one is
-  the fully qualified form's job.
-- **system** omitted → **the system block the link is written under**. Anywhere
-  under `sohl:` is `sohl`; anywhere under `hm3:` is `hm3`; **anywhere else** —
-  top-level frontmatter, `data:`, and body prose — is `none`. The enclosing block
-  decides at any depth, so `sohl.items[3].model` and `sohl.system.body.structure`
-  default alike; the field has no say.
-
-**Under `none`, a system-bearing type addresses its documentation.** A note's
-`none` address _is_ its `doc<type>` journal — the Item is the one with a system —
-so a prose `[[affiliation-sirvadar|Sirvadar]]` names the page, which is what
-prose almost always means. A prose link that means the **Item** states the
-system: `[[sohl-affiliation-sirvadar|…]]`.
-
-Only a type whose own document carries a system is redirected this way. A
-`macro` and the map types have documentation journals too, but their own
-documents are core ones already at `none`, so `macro-autoattack` names the Macro
-and `docmacro-autoattack` its journal — two live addresses.
+An omitted segment is a default, not a wildcard. Every short form expands to one
+complete Address before lookup.
+
+- **Package:** the current package. A short address never falls through to a
+  dependency.
+- **System in `[[link|text]]`:** `note`, for every note type. Use an explicit
+  game system to name its Actor or Item, or `none` to name a systemless target.
+- **System in `![[link|text]]`:** `none`. An embed names an image or icon asset;
+  it also supplies `image` as the type of a bare shortcode.
+- **System in frontmatter:** a system block such as `sohl:` or `hm3:` supplies
+  its game system. Other Address fields default to `note`, except fields
+  declared for images, icons or folders, which default to `none`.
+
+For example, `[[macro-autoattack|Automated Attack]]` names the readable macro
+note, while `[[none-macro-autoattack|Automated Attack]]` names the Foundry Macro.
+`![[icon-anvil|Anvil]]` names the systemless icon asset.
 
 **A complete Address is lowercase throughout.** Every segment — package,
 system, type and shortcode alike — contains only lowercase ASCII letters and
@@ -1572,7 +1580,7 @@ A **`Wikilink`** is how body prose names something:
 The brackets, the `#<anchor>` and the `|<text>` label are the Wikilink's own.
 What sits inside them is an `Address` like any other — read by the same grammar,
 written at any of its lengths, and taking each omitted segment from where the
-link is written, which for body prose is this package and system `none`. So
+link is written, which for body prose is this package and system `note`. So
 nothing about resolution belongs to the bracketed form: a wikilink and a
 frontmatter field ask the same question of the same value, and the findings above
 are the answers either of them gets.
@@ -2054,10 +2062,10 @@ system a note might write. A package shipping for a second system declares
 `system:` on a pack of each class it compiles.
 
 That includes actors. A being producing its Actor and nothing else would be
-the one system-bearing note with no address at `none`, leaving a prose link
+a system-bearing note with readable content, giving a prose link
 naming it nowhere to land. It carries a documentation journal like every other
 such note, addressed
-`<package>-none-docbeing-<shortcode>` beside the Actor's
+`<package>-note-being-<shortcode>` beside the Actor's
 `<package>-<system>-being-<shortcode>`.
 
 **A being keeps its prose inline as well.** `system.appearance` and
@@ -2488,6 +2496,7 @@ Generates a living (or undead, or spirit) being.
 | `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                       |
 | `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — `[]` where none apply; `null` is an error. |
 | `occupation`                | `string`                                       | Name of the character's occupation                                                               |
+| `social`                    | `Map<string, unknown>`                         | The being's social profile                                                                       |
 | `stations`                  | `Address[]`                                    | Name of the stations the character belongs to                                                    |
 | `lore`                      | `Address[]`                                    | Lore concerning this being — the people it is of, the standing it holds, the law it lives under  |
 | `homes`                     | `Address[]`                                    | Place the being calls home                                                                       |
@@ -2750,7 +2759,8 @@ no Foundry document: it is a page and nothing else.
 It declares a `shortcode` — conventionally `root` — because that is what a
 link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and it
 resolves to `/<package>/`. The shortcode names the page in links; its address
-is the package root. `title` defaults to `packageBuild.manifest.title`; a
+is the package root. The page heading reads `name.full` and defaults to
+`packageBuild.manifest.title`; a
 `description` and a `banner` are read by the theme's hero; any other
 top-level key is passed through to the page as a theme parameter.
 
@@ -4065,7 +4075,7 @@ await CONFIG.SOHL.class.Utility.currentCombatantAttack();
 
 Three rules follow, and each is deliberate. The anchor names the **page**, not
 the heading text, so the heading may be worded freely and
-`[[docmacro-autoattack#script]]` still opens exactly this page. The fence must
+`[[macro-autoattack#script]]` still opens exactly this page. The fence must
 be **tagged** — an untagged fence is a code sample whose language nobody stated,
 and treating it as executable would make an illustrative snippet the macro. And
 only the **first** tagged fence counts, so a note may document its macro
@@ -4141,8 +4151,8 @@ persists in the pack.
 **Each address names the note's own document.** That is the same rule `pack:`
 follows, so there is one answer and not two. A note that compiles into _two_
 documents — an item and the JournalEntry its prose became — puts the second in a
-bundle only when the bundle names it by its own `doc…` address:
-`miscgear-bowlcer` is the item, `docmiscgear-bowlcer` its description page.
+bundle when the bundle names its `note` Address:
+`sohl-miscgear-bowlcer` is the Item, `miscgear-bowlcer` its description page.
 
 **An address that resolves to nothing fails the build.** A `folder` address is
 refused with a message of its own: a folder materialises in every pack holding

package/docs/getting-started.md

@@ -133,9 +133,7 @@ npm install --save-dev @heroiclands/package-build
 ```
 
 That installs `package-build`, the packaging half, and `content-build`, the
-content half, into `node_modules/.bin`. It also installs the optional
-`heroiclands-content-language-server` for editor navigation. Every build command
-below uses one of the first two binaries. Run them through `npx`, or wire them into npm scripts as
+content half, into `node_modules/.bin`. Run them through `npx`, or wire them into npm scripts as
 [`project-setup.md`](project-setup.md) describes.
 
 **How it worked:** `npx package-build --version` prints the installed version.