Codex/prepare protocol id refs

README.md

@@ -8,6 +8,33 @@ The renderer uses [kingc95/XanaNode-Core-SDK](https://github.com/kingc95/XanaNod
 
 This theme turns a Hugo content tree into a readable website plus machine-readable XanaNode substrate artifacts.
 
+## Proper Build
+
+Run these from the `XanaNode-Hugo/` theme repository.
+
+For the example site bundled with the theme, the normal production build is:
+
+```bash
+npm run example:build
+```
+
+That runs `npm run prepare` first, which validates Markdown-authored nodes plus imported protocol JSON, regenerates the protocol artifacts, and then runs Hugo against `exampleSite`.
+
+Use this before publishing or checking the example:
+
+```bash
+npm run validate
+npm run example:build
+```
+
+Use this for local theme/example development:
+
+```bash
+npm run example:dev
+```
+
+Do not use plain `hugo` by itself unless you already ran `npm run prepare`; otherwise generated protocol files can be stale.
+
 ## What It Publishes
 
 A Hugo site using this theme can publish:
@@ -49,15 +76,72 @@ The build tool validates generated substrate artifacts with `@xananode/core`. It
 
 `tools/prepare-xananode.mjs` intentionally remains in this repository because it is Hugo-specific glue. It reads Hugo Markdown/front matter conventions, resolves Hugo shortcodes, writes files into Hugo's `data/` and `static/` folders, and prepares the viewer feed used by the theme. Protocol rules should live in Core; renderer concerns should stay here. If this script needs a protocol rule that Core does not expose, that rule belongs upstream in Core rather than being reimplemented permanently in Hugo.
 
+Configured `params.xananode.links` are part of the site projection. Public links without an existing `node` are emitted as lightweight `source` nodes so the graph can represent project homes, social profiles, support pages, and documentation links with normal substrate identity. Set `private: true` or `generate_node: false` on a link when it should remain a UI link only.
+
+Generated link nodes can also connect back into the substrate with flat config keys:
+
+```yaml
+params:
+  xananode:
+    links:
+      - label: "Support"
+        url: "https://github.com/sponsors/example"
+        summary: "Support ongoing substrate creation."
+        relationship_type: "supports"
+        relationship_target: "xananode"
+```
+
 Current generated protocol files include:
 
 - `substrate.json`: substrate manifest with namespace, version, imports, and schema version.
+- `nodes-index.json`: static-host friendly index of published node record files.
 - `relationships.json`: typed protocol relationship records.
 - `nodes/*.json`: per-node protocol records with incoming/outgoing relationship summaries.
 - `schemas/*.json`: canonical registries and substrate/report schemas.
+- `xananode-viewer.json`: browser-ready read-only viewer feed derived from the protocol records.
+
+## Import Protocol JSON
+
+Hugo sites do not need to recreate every protocol object as Markdown.
+
+Drop generated and validated protocol JSON into one of these source folders:
+
+```text
+imports/
+data/imports/
+data/xananode-imports/
+```
+
+Supported import shapes:
+
+- A substrate node object.
+- An array of substrate node objects.
+- An object with a `nodes` array.
+- A relationship-list object with a `relationships` array.
+- An array of relationship objects.
+
+Then run:
+
+```bash
+npm run validate
+npm run build
+```
+
+The prepare step merges Markdown-authored nodes with imported protocol JSON, validates the combined substrate through Core, writes `/substrate.json`, `/nodes-index.json`, `/nodes/*.json`, `/relationships.json`, and updates `/xananode-viewer.json` for the browser.
+
+Use Markdown for prose and authored pages. Use JSON imports for existing Core or Workspace records, generated relationship files, federation packs, schema packs, or any substrate data you do not want to hand-copy into front matter.
+
+Core owns the review logic. The Hugo prepare step asks `@xananode/core` to analyze the current substrate plus incoming packs for possible same-entity merges, incoming relationships that touch existing nodes, possible Markdown links, and possible transclusions. Hugo only formats those Core suggestions for static review.
 
 The example site also includes a "Protocol Artifacts Trail" that explains the concrete files, reports, registries, extension model, and federation governance described by the protocol.
 
+The bundled example uses protocol JSON packs:
+
+- `params.xananode.packs` in `exampleSite/hugo.yaml` mounts the protocol minimal substrate from the Core/Protocol submodule.
+- `exampleSite/imports/lineage/` is the extended XanaNode lineage pack, covering the historical and conceptual branches that lead into XanaNode.
+
+These are intentionally not recreated as Markdown pages. They demonstrate both pack modes: a mounted pack remains governed by its source repository, while a local import pack can later be absorbed after review. Generated or validated protocol JSON can be mounted or dropped into a Hugo site, merged with authored Markdown nodes, validated by Core, and rendered by the read-only viewer.
+
 ## Core Authoring Model
 
 ### Nodes
@@ -182,7 +266,15 @@ npm run validate
 npm run example:dev
 ```
 
-The example site is intentionally self-hosting: it explains XanaNode using XanaNode nodes, relationships, trails, schemas, and generated protocol artifacts.
+The example site is intentionally small enough to copy: it shows how XanaNode nodes, relationships, trails, schemas, and generated protocol artifacts render in Hugo. The fuller XanaNode doctrine, lineage, and implementation stack should be treated as a substrate pack that can be mounted when a site wants that layer.
+
+To generate the optional canonical pack from the current example substrate:
+
+```bash
+npm run pack:canonical
+```
+
+That writes `exampleSite/packs/xananode-canonical/`. It is present as an opt-in pack in `exampleSite/hugo.yaml` with `enabled: false`; flip that to `true` when you want Hugo to mount it. In normal use, Workspace should provide the friendly pack picker and import/merge review flow, while Core enforces the protocol behavior and Hugo renders the resulting artifacts.
 
 ## Use This Theme In Another Hugo Site
 
@@ -253,10 +345,25 @@ exist, the viewer falls back to `start-here`, then to the first available node.
 Keep `namespace` stable once published. It becomes part of protocol ids,
 fragment addresses, generated node records, and federation references.
 
+Optional packs live under `params.xananode.packs`:
+
+```yaml
+params:
+  xananode:
+    packs:
+      - id: "xananode.canonical"
+        source: "packs/xananode-canonical"
+        mode: "mounted"
+        enabled: false
+```
+
+Use `mounted` when the pack should remain externally governed, `imported` when generated local artifacts should include copied pack records with provenance, and `merged` when Workspace/Core should reconcile identity and conflicts through review. `absorbed` remains a legacy alias for `imported`, but new configs should not use it.
+
 White-label the content too:
 
 - Replace or remove the example nodes under `content/`.
 - Keep any example node only if it is genuinely part of your substrate.
+- Mount optional XanaNode packs instead of copying canonical XanaNode content into your own substrate.
 - Replace `xananode-icon.svg`, social images, and brand copy.
 - Update `params.keywords`, analytics settings, and `baseURL`.
 - Choose a default visual mode from the in-browser settings; reader choices are