@heroiclands/package-build 22.12.3 → 22.13.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @heroiclands/package-build
 
+## 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

@@ -596,16 +596,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 +676,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 +1063,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 +1078,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.
@@ -1268,85 +1268,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 +1565,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 +2047,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
@@ -4065,7 +4058,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 +4134,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.

package/engine/address.mjs

@@ -79,41 +79,25 @@
  * to guess which sense was meant. The cost is that `<package>-<type>-<shortcode>`
  * is **not** a written form, so a link into another package states its system.
  *
- * ## The three rules a complete tuple applies
- *
- * - **`system` is derived from the type, then defaulted.** An asset type and a
- *   documentation journal are {@link NO_SYSTEM} because a file and a
- *   JournalEntry belong to no game system, and the segment is therefore a
- *   property of the type rather than of where the reference was written.
- *   Everything else takes the written system, then the position's default.
- * - **`type` may not survive unchanged.** A system-bearing type reached at
- *   `none` is redirected to `doc<type>`, because a note's `none` address *is*
- *   its documentation journal — the Item is the one with a system.
- * - **Acceptability accepts a type's documentation form.** A position that
- *   accepts `weapongear` accepts `docweapongear`, so a target addressed by its
- *   documentation journal is acceptable wherever the note itself would be.
+ * ## Defaults belong to the citing position
+ *
+ * Ordinary wikilinks default to `note`, embeds default to `none`, and typed
+ * frontmatter fields supply their declared system. The authored type stays
+ * the type in the complete tuple. A `doc<type>` qualifier is accepted as an
+ * input spelling for a readable note and resolves to `note-<type>`.
  *
  * ## The tuple keeps no memory of how it was written
  *
  * An abbreviation is a *rendering*, not a different value: `being-kaldor` in a
- * `thalorna` note and `thalorna-none-being-kaldor` are the same Address, and
- * they parse to the same four fields. So does the pair `weapongear-dgr` in prose
- * and `docweapongear-dgr` anywhere, because both name the one documentation
- * journal. Nothing here records what the author typed — a tuple that did would
- * make identity depend on a spelling, and two notes naming one document would
- * compare unequal.
+ * `thalorna` note and `thalorna-note-being-kaldor` are the same Address, and
+ * they parse to the same four fields. Nothing here records what the author
+ * typed — a tuple that did would make identity depend on a spelling.
  *
  * The converse matters just as much: **one written string is two Addresses at
  * two positions**, because the positions supply different defaults.
  * `skill-wpnc` under `sohl.items` defaults its system from the block and names
- * the **Item**; the same string in body prose defaults to `none`, is redirected,
- * and names the **page**. Only the resolved tuple can tell them apart.
- *
- * That is why {@link acceptsType} widens the accepted set rather than reading a
- * remembered pre-redirect type off the tuple. The redirect is not reversible
- * from the four segments alone: `docmacro-autoattack` addresses a `macro`'s
- * journal while `macro-autoattack` addresses the Macro, so `doc`-stripping is a
- * question about the type vocabulary, not about the tuple.
+ * the Item; the same string in body prose defaults to `note` and names the
+ * readable page. Only the resolved tuple can tell them apart.
  *
  * ## What this module does not do
  *
@@ -132,17 +116,15 @@
 // `engine/systems.mjs` imports nothing but `engine/address-charset.mjs`, so the
 // direction is toward the leaf and cannot close a cycle.
 import { isAddressSegment } from "./address-charset.mjs";
-import { NO_SYSTEM, assertSystemSegment, isSystemSegment } from "./systems.mjs";
-// The asset vocabulary, for the one thing the address grammar asks of it:
-// whether a type's `<system>` segment is fixed. `engine/asset-types.mjs` is a
-// leaf, so the direction cannot close a cycle.
-import { isAssetType } from "./asset-types.mjs";
+import { NO_SYSTEM, NOTE_SYSTEM, assertSystemSegment, isSystemSegment } from "./systems.mjs";
+// Document subtype maps identify the system of a note's own Actor or Item.
 import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 // `ids.mjs` is a leaf with no local imports, and `pack-config.mjs` reaches only
 // the configuration loader and the diagnostics writer — neither reads an
 // address, so the grammar sits below everything that consumes it.
-import { currentType, ITEM_PACK, packForType } from "./ids.mjs";
+import { currentType, ITEM_PACK, JOURNAL_TYPES, packForType } from "./ids.mjs";
+import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
 export { NO_SYSTEM };
@@ -166,32 +148,18 @@ export const ADDRESS_SEPARATOR = "-";
  */
 export const CANONICAL_KEY_SEGMENTS = 4;
 
-/**
- * The qualifier prefix that addresses a note's **documentation** rather than
- * the note's own document: `docskill-wpnc` is the JournalEntry that
- * `skill-wpnc`'s prose compiled into.
- *
- * Every doc-carrying type has a `doc<type>` counterpart, formed by prefix and
- * never enumerated, so the prefix itself is the whole of that vocabulary.
- *
- * @type {string}
- */
+/** The accepted `doc<type>` input prefix for readable note links. */
 export const ITEM_DOC_PREFIX = "doc";
 
 /** Package, system and type are one spelling each, so they fold to lowercase. */
 const norm = (s) => String(s).toLowerCase().trim();
 
 /**
- * A complete Address: four segments, and nothing else.
- *
- * `type` is the segment the canonical string carries, after the `doc<type>`
- * redirect. There is no fifth field recording the written form, because the
- * written form is a rendering rather than part of the value.
+ * A complete Address: four segments, with no memory of the authored form.
  *
  * @typedef {object} AddressTuple
  * @property {string} package - The owning **content** package.
- * @property {string} system - The system whose document this addresses, or
- *   `none`.
+ * @property {string} system - `note`, `none`, or a game system id.
  * @property {string} type - The type segment of the canonical Address.
  * @property {string} shortcode - The note's `shortcode`.
  */
@@ -218,29 +186,8 @@ const norm = (s) => String(s).toLowerCase().trim();
  */
 
 /**
- * Every content type whose **prose compiles into a JournalEntry of its own**,
- * addressed by the virtual `doc<type>` qualifier.
- *
- * Every item type, every actor type, every map type, plus `macro` — a macro
- * note's body documents the script the note also compiles into a Macro, which
- * is the same shape as an item and its description: one note, two documents,
- * the prose living in the journals pack.
- *
- * **One set, read by the compilers and by the grammar alike.** The journals
- * pass decides what to compile from it, the link manifest decides what to
- * publish a `doc<type>` entry for, and the parser decides whether `doc<type>`
- * is a legal type segment. Held apart, the three drift into a manifest that
- * asserts documentation nothing compiled, a compiled entry no consumer can
- * address, or an authored `doc<type>` link that stops parsing. It is composed
- * exactly once, in `defineConfig`, and read from there — never recomposed at a
- * call site.
- *
- * `doc` notes are absent, for the reason that applies to them alone: a `doc`
- * note's single document *is* its prose, so there is no second document for a
- * `doc<type>` address to name.
- *
- * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration.
+ * The configured types whose prose compiles into a separate JournalEntry.
+ * The journal has a `note` Address with the authored type segment.
  *
  * @returns {ReadonlySet<string>} The configured doc-carrying types.
  */
@@ -265,50 +212,20 @@ export function hasDocEntry(type) {
     return docEntryTypes().has(String(currentType(type)));
 }
 
-/**
- * Whether a note type's **own** document carries a game system.
- *
- * True for the types some shipped map compiles into an Item or an Actor; false
- * for the core-document types — `doc`, `lore`, `place`, `scenario`, `macro` and
- * the map types — whose documents Foundry itself defines and which therefore
- * already live at `none`.
- *
- * It is what the `doc<type>` redirect tests rather than {@link hasDocEntry}: a
- * `macro` has a documentation journal *and* a `none` address of its own, so
- * redirecting on "has a doc entry" would collapse two live addresses into one
- * and a `[[macro-autoattack|]]` would stop naming the Macro.
- *
- * @param {string} type - The note type.
- * @returns {boolean} True when the type compiles into a system document.
- */
-function isSystemBearing(type) {
-    return systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS) !== NO_SYSTEM;
+/** The segment of a note's own document. */
+export function ownDocumentSystem(type) {
+    return JOURNAL_TYPES.has(String(type)) || type === HOMEPAGE_TYPE ?
+            NOTE_SYSTEM
+        :   systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS);
 }
 
 /**
- * Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is
- * not one.
- *
- * A document and its documentation are two documents in two packs, so they need
- * two addresses. `skill-wpnc` is the item; `docskill-wpnc` is the JournalEntry
- * its prose compiled into, and `docmacro-autoattack` is the same arrangement
- * for a macro.
- *
- * The virtual form exists for a type that carries separate documentation
- * ({@link docEntryTypes} — the set the journals compiler and the link manifest
- * read too), **or** for one that routes to the items pack. The second clause
- * covers the open, unenumerated set: types that compile into items are not
- * enumerated anywhere, and a foreign package may publish an item type this
- * build has never heard of. Dropping it would silently unlink every `doc<type>`
- * address into such a package.
- *
- * A **real** type of the same name always wins: the virtual reading is only
- * consulted for a qualifier no authored note claims.
- *
- * @param {string} qualifier - The already-normalised type segment.
- * @param {Set<string>} types - Every type the content tree contains.
- * @returns {string|null} The underlying document type, or `null` when the
- *   qualifier is not a virtual one.
+ * Read a `doc<type>` input qualifier as the underlying authored type.
+ * A real type with that spelling takes precedence.
+ *
+ * @param {string} qualifier - The type segment from the input.
+ * @param {Set<string>} types - Types in the content tree.
+ * @returns {string|null} The underlying type, or `null`.
  */
 export function resolveItemDocType(qualifier, types) {
     if (types.has(qualifier)) return null; // a real type owns its own name
@@ -445,21 +362,11 @@ export function renderAddress(tuple) {
 }
 
 /**
- * Whether the type an Address names is one this position accepts.
- *
- * The second of the two questions, and separate from the first because the
- * accepted **set** is a property of the position while the grammar is not.
- *
- * **An accepted type carries its documentation form with it.** A position
- * accepting `weapongear` accepts `docweapongear`, because the journal that
- * documents a weapon is the same thing to a position that wanted a weapon — and
- * a prose address of one *is* the journal, so refusing it would refuse the form
- * an author most often writes. It is the widening `defineConfig` applies to the
- * types a package may claim, applied here to the types a position may take.
+ * Whether the canonical type an Address names is accepted at this position.
  *
- * @param {AddressTuple} tuple - A parsed Address.
- * @param {Iterable<string>} allowed - The types this position accepts.
- * @returns {boolean} True when the Address names one of them.
+ * @param {AddressTuple} tuple - A complete Address.
+ * @param {Iterable<string>} allowed - Accepted types.
+ * @returns {boolean} Whether the type is accepted.
  */
 export function acceptsType(tuple, allowed) {
     const type = norm(tuple?.type ?? "");
@@ -467,7 +374,7 @@ export function acceptsType(tuple, allowed) {
     for (const one of allowed ?? []) {
         const want = norm(one);
         if (!want) continue;
-        if (type === want || type === `${ITEM_DOC_PREFIX}${want}`) return true;
+        if (type === want) return true;
     }
     return false;
 }
@@ -475,9 +382,7 @@ export function acceptsType(tuple, allowed) {
 /**
  * Apply the defaults to a partial reading, giving a complete Address.
  *
- * The three rules of the module note, applied in the order they depend on each
- * other: the package, then the system the type may fix, then the redirect the
- * system may force.
+ * Complete a parsed Address using the citing position's package and system.
  *
  * @param {{type: string, shortcode: string, package?: string, system?: string,
  *   itemDoc?: boolean}} read - A partial reading, as {@link readQualifier}
@@ -490,27 +395,8 @@ export function completeAddress(read, where = {}) {
     if (isAddressTuple(read)) return read;
     const written = read.type;
     const pkg = read.package ?? where.package;
-    // A documentation journal is a core document, so it is `none` however it was
-    // reached, and an **asset** is `none` for a stronger reason: a file belongs
-    // to no game system, so the segment is a property of the type rather than of
-    // where the reference was written. Without that, a `sohl:` block naming
-    // `icon-anvil` would expand to `sohl-sohl-icon-anvil` and resolve to
-    // nothing, which is exactly where an embedded item's art is written.
-    // Otherwise the block's system, which body prose reports as `none`.
-    const system =
-        read.itemDoc || isAssetType(written) ?
-            NO_SYSTEM
-        :   (read.system ?? where.system ?? NO_SYSTEM);
-    // **Under `none`, a system-bearing type addresses its documentation
-    // journal.** A note's `none` address *is* its `doc<type>` entry — the Item
-    // is the one with a system — so a prose `[[affiliation-sirvadar|…]]` names
-    // the page, which is almost always what prose means. A value that means the
-    // Item states the system and gets it. A `doc<type>` written explicitly is
-    // `none` wherever it appears, even inside a system block: no game system
-    // defines a JournalEntry.
-    const redirected = system === NO_SYSTEM && isSystemBearing(written);
-    const type = read.itemDoc || redirected ? `${ITEM_DOC_PREFIX}${written}` : written;
-    return addressTuple({ package: pkg, system, type, shortcode: read.shortcode });
+    const system = read.itemDoc ? NOTE_SYSTEM : (read.system ?? where.system ?? NOTE_SYSTEM);
+    return addressTuple({ package: pkg, system, type: written, shortcode: read.shortcode });
 }
 
 /**