Commit e23584

2026-09-14 10:46:55 Dan Alexander: Add company wiki standards and VoxelCore docs This change establishes the shared company knowledge structure, governance, engineering, security, and incident/change standards. It also adds the VoxelHorizons product tree with a complete VoxelCore documentation set covering architecture, operations, authoring, version support, resource pack compilation, runtime reloads, and testing/release workflows.

/dev/null .. company/architecture-decisions.md
@@ 0,0 1,14 @@
+	# Architecture Decisions
+
+	Use an Architecture Decision Record (ADR) for a choice that will constrain future work or otherwise be expensive to rediscover.
+
+	Good ADR subjects include persistence models, compatibility strategy, identity schemes, protocol boundaries, framework selection and cross-product service contracts. Routine implementation details do not need an ADR.
+
+	## Decision states
+
+	- **Proposed** — under review.
+	- **Accepted** — current decision.
+	- **Superseded** — replaced by a newer ADR; retain the old record and link both directions.
+	- **Rejected** — considered but not chosen; retain when the rejected option is likely to recur.
+
+	An ADR should explain context, decision, alternatives, consequences and follow-up work. Use [[Templates/Architecture-Decision-Record]].
/dev/null .. company/change-management.md
@@ 0,0 1,17 @@
+	# Change Management
+
+	Use a proportional process: small reversible changes need less ceremony than migrations or compatibility changes, but every production-affecting change needs an understood verification and rollback path.
+
+	## Before a change
+
+	Identify the affected product/service, expected behaviour, dependencies, data/config migrations, compatibility impact, validation method and rollback method. For high-risk changes, record an explicit maintenance window and recovery owner outside the wiki if required.
+
+	## During a change
+
+	Capture the deployed version/commit and avoid mixing unrelated changes into the same recovery boundary. Stop when validation fails rather than stacking further speculative changes over an unknown state.
+
+	## After a change
+
+	Verify the intended behaviour, record any operator-facing differences, update affected wiki reference pages, and close temporary migration instructions once they are no longer needed.
+
+	For releases, start from [[Templates/Release-Checklist]].
/dev/null .. company/documentation-standards.md
@@ 0,0 1,56 @@
+	# Documentation Standards
+
+	These conventions keep the wiki predictable as more Soatrix products are added.
+
+	## Information architecture
+
+	Use this broad hierarchy:
+
+	```text
+	Home
+	├── Company
+	│ ├── shared standards
+	│ ├── governance
+	│ └── operating practices
+	├── Products
+	│ └── <product family>
+	│ └── <product or service>
+	│ ├── overview/current status
+	│ ├── user or operator guides
+	│ ├── architecture/developer reference
+	│ └── roadmap
+	└── Templates
+	```
+
+	Do not create a new top-level category when an existing one fits.
+
+	## Naming
+
+	- Give every page one clear `# H1` title.
+	- Keep Git filenames and directories simple, lower-case and URL-safe.
+	- Prefer descriptive page names over generic names such as `notes` or `misc`.
+	- Use the first heading for the human-readable title.
+
+	## Writing rules
+
+	- State exact versions, paths and dates when they affect correctness.
+	- Put commands and configuration in fenced code blocks.
+	- Explain destructive or irreversible effects immediately before the action.
+	- Separate **current behaviour**, **known limitations** and **planned work**.
+	- Prefer one canonical explanation and link to it rather than copying the same rule across pages.
+	- Keep troubleshooting symptom-driven: symptom → likely cause → check → recovery.
+
+	## Repository-backed products
+
+	A well-maintained product tree should normally contain:
+
+	- `Index` — purpose and navigation;
+	- `Current Status` — baseline commit, supported surface and notable recent changes;
+	- `Getting Started` — minimum path to a working system;
+	- `Architecture` — boundaries and data flow;
+	- configuration and command/reference pages;
+	- build/testing/release information;
+	- operations/troubleshooting;
+	- roadmap/scope.
+
+	Use [[Templates/Product-Documentation]] when starting a new product.
/dev/null .. company/engineering-standards.md
@@ 0,0 1,31 @@
+	# Engineering Standards
+
+	This page establishes baseline expectations for Soatrix-maintained software. Individual products may impose stronger requirements.
+
+	## Design
+
+	- Prefer explicit interfaces and dependency direction over cross-module reach-through.
+	- Keep stable identity separate from presentation/rendering identifiers.
+	- Validate external or authored input at the boundary before it enters runtime state.
+	- Prefer immutable published state where practical; publish replacements atomically rather than mutating a live registry piecemeal.
+	- Make compatibility claims explicit and testable. A version range is not equivalent to a validated exact-version matrix.
+
+	## Changes
+
+	A change is ready to merge when its behavioural contract is understood, relevant tests are added or updated, and operations/documentation are changed where needed. Compatibility changes should include regression coverage at the boundary they introduce.
+
+	## Failures
+
+	- Fail startup when continuing would publish corrupt or unsupported state.
+	- For reloadable systems, build and validate candidate state before replacing known-good state.
+	- Error messages should identify the invalid input or dependency chain rather than masking it with a generic failure.
+
+	## Dependencies
+
+	- Pin or constrain dependencies deliberately.
+	- Isolate platform/version-specific APIs behind adapters when multiple runtime generations are supported.
+	- Avoid leaking implementation-specific APIs into common modules unless the common contract genuinely depends on them.
+
+	## Testing
+
+	Use multiple layers where appropriate: unit tests for rules, integration tests for component boundaries, and real-runtime smoke tests for compatibility claims that mocks cannot establish.
/dev/null .. company/incident-response.md
@@ 0,0 1,18 @@
+	# Incident Response
+
+	Incidents should optimise first for safe restoration, then for understanding and prevention.
+
+	## Lifecycle
+
+	1. **Detect and scope** — identify the user-visible impact and affected systems.
+	2. **Stabilise** — stop further damage; prefer a known-good rollback when appropriate.
+	3. **Recover** — restore the service and verify from the user's perspective.
+	4. **Preserve evidence** — keep relevant logs, timestamps, deploy IDs and configuration diffs.
+	5. **Review** — document contributing conditions and follow-up actions without blame.
+	6. **Improve** — implement fixes, monitoring and documentation changes.
+
+	## Communication
+
+	Use exact times with time zones for material events. Distinguish confirmed facts from hypotheses. Never paste secrets into incident pages.
+
+	Use [[Templates/Incident-Review]] for the durable record and create or update a runbook when the incident revealed a repeatable recovery procedure.
/dev/null .. company/index.md
@@ 0,0 1,18 @@
+	# Company Knowledge System
+
+	The **Company** tree contains rules and shared knowledge that apply across Soatrix products. It should remain stable even as individual products are created, renamed or retired.
+
+	## Core pages
+
+	- [[Company/Wiki-Governance]] — ownership, lifecycle and source-of-truth rules.
+	- [[Company/Documentation-Standards]] — writing and page-structure conventions.
+	- [[Company/Engineering-Standards]] — baseline engineering expectations.
+	- [[Company/Security-and-Access]] — safe handling of credentials, access and sensitive material.
+	- [[Company/Change-Management]] — how production-affecting changes should be planned and verified.
+	- [[Company/Incident-Response]] — incident lifecycle and post-incident documentation.
+	- [[Company/Architecture-Decisions]] — when and how to record ADRs.
+	- [[Company/Service-Catalogue]] — how products, services and dependencies should be indexed.
+
+	## Boundary
+
+	This section defines **shared practice**, not product behaviour. VoxelCore implementation details, for example, belong under [[Products/Voxel-Horizons/VoxelCore/Index]].
/dev/null .. company/security-and-access.md
@@ 0,0 1,27 @@
+	# Security and Access
+
+	The wiki should describe **how** to obtain or rotate access, never store the secret itself.
+
+	## Never commit
+
+	Do not place these in wiki Markdown, attachments or repository history:
+
+	- passwords;
+	- API tokens and personal access tokens;
+	- OAuth/OIDC client secrets;
+	- private keys or recovery codes;
+	- database connection strings containing credentials;
+	- session cookies;
+	- private customer or employee data that does not belong in the documentation repository.
+
+	## Document instead
+
+	Record the system name, purpose of the credential, where it is managed, who/which role is expected to have access, rotation expectations, and the recovery/escalation procedure.
+
+	## Least privilege
+
+	Service and human access should be scoped to the minimum permissions required. Administrative credentials should not be reused as application credentials.
+
+	## Incident handling
+
+	If a secret is accidentally committed, deleting the page is insufficient because Git history may retain it. Rotate/revoke the secret first, then remove it from current content and rewrite repository history only when appropriate. Record the event using [[Templates/Incident-Review]] without reproducing the exposed secret.
/dev/null .. company/service-catalogue.md
@@ 0,0 1,24 @@
+	# Service Catalogue
+
+	The service catalogue is the navigation layer between business/product names and their technical components.
+
+	## Catalogue model
+
+	Each product or service should document:
+
+	- purpose and audience;
+	- owning product family/team or maintainer;
+	- source repository/repositories;
+	- production/runtime entry points;
+	- upstream/downstream dependencies;
+	- authentication and data stores at a descriptive level;
+	- monitoring/runbook links;
+	- lifecycle status such as active, experimental, deprecated or retired.
+
+	## Current catalogue
+
+	### Voxel Horizons
+
+	- **VoxelCore** — version-aware Minecraft content foundation. See [[Products/Voxel-Horizons/VoxelCore/Index]].
+
+	Additional Soatrix products can be added beneath [[Products/Index]] without changing the company-level structure.
/dev/null .. company/wiki-governance.md
@@ 0,0 1,49 @@
+	# Wiki Governance
+
+	The wiki is the human-readable knowledge layer for Soatrix. It is Git-backed so documentation changes have history, authorship and reversible revisions.
+
+	## Source-of-truth hierarchy
+
+	Use this order when sources disagree:
+
+	1. Running production behaviour and validated runtime configuration.
+	2. Merged source code and automated tests on the product's documented baseline branch/commit.
+	3. Product wiki reference pages.
+	4. Repository README files and release notes.
+	5. Planning documents, tickets, chat discussions and historical notes.
+
+	A lower source should be updated when it is proven stale; it should not be used to override a higher source silently.
+
+	## Page lifecycle
+
+	Every substantive product area should be recognisable as one of four states:
+
+	- **Reference** — describes implemented behaviour.
+	- **Runbook** — executable operational procedure.
+	- **Decision** — durable architectural or policy rationale.
+	- **Plan** — proposed/future work that is not yet a supported contract.
+
+	Avoid wording that makes a plan sound implemented.
+
+	## Verification dates
+
+	Pages that describe fast-moving software should state the baseline used for verification. For repository-backed products, record the branch and abbreviated commit SHA near the top of the product's **Current Status** page. Do not place a mutable word such as “latest” in a durable page without a date or commit.
+
+	## Changes
+
+	When a code change alters a documented contract, update the relevant wiki page in the same release/change window. Examples include:
+
+	- a new supported runtime version;
+	- a command or permission change;
+	- a configuration schema change;
+	- a new content authoring field;
+	- a different persistence or rollback guarantee;
+	- a changed operational requirement.
+
+	## Deleting and superseding pages
+
+	Prefer a short superseded page that links to the replacement when old links are likely to exist. Delete only when the page was erroneous, sensitive or has no useful historical navigation value.
+
+	## Git safety
+
+	The wiki repository history may contain old text even after a page is edited. Never commit passwords, private keys, tokens, one-time secrets, database credentials or personal data that should not persist in Git history. Use a secrets manager or the relevant platform's protected configuration facility instead.
home.md ..
@@ 1,28 1,29 @@
-	## Welcome to your wiki!
-
-	Your Otter Wiki is up and running.
-
-	This is your [[Home]] Page, the first page you see when you access your
-	wiki.
-
-	The first steps you might want to do:
-
-	1. [Register an account](/-/register). The very first account is an
-	admin account which is able to configure the wiki.
-	2. Check the [configuration](/-/admin#application_preferences) of your wiki.
-	You can change its name, configure the permissions necessary to
-	view and edit pages or upload attachments.
-	3. If you require users to confirm their email address (recommended),
-	make sure that you will configure and test your [Email Preferences](/-/admin#mail_preferences).
-	4. [Edit your Home](/Home/edit)! Do not like the change? Visit the
-	page [history](/Home/history) and revert any change ever made.
-	5. You can [attach](/Home/attachments) images and other files to any page
-	and then display them and link to them inside the page.
-	6. [Create new pages](/-/create)! If you need help with the Markdown syntax,
-	check out the [Markdown guide](/-/help/syntax).
-	7. Read the [user guide](/-/help) and learn about An Otter Wikis features.
-
-	We hope that An Otter Wiki is just what you are looking for.
-	If you have any suggestions, feature requests or run into any
-	issues, please reach out and report them
-	via [github](https://github.com/redimp/otterwiki/issues).
+	# Soatrix Knowledge Base
+
+	Welcome to the central technical and operational knowledge base for **Soatrix** products and services.
+
+	This wiki is designed as a long-lived source of truth rather than a collection of disconnected notes. Company-wide standards live under **Company**, product documentation lives under **Products**, and reusable documentation patterns live under **Templates**.
+
+	## Start here
+
+	- [[Company/Index]] — how the knowledge base is organised and governed.
+	- [[Products/Index]] — product catalogue and technical documentation.
+	- [[Templates/Index]] — reusable page structures for future services, decisions, incidents and releases.
+
+	## Current product documentation
+
+	### Voxel Horizons
+
+	- [[Products/Voxel-Horizons/Index]]
+	- [[Products/Voxel-Horizons/VoxelCore/Index]] — complete VoxelCore item/content MVP documentation.
+	- [[Products/Voxel-Horizons/VoxelCore/Current-Status]] — implementation snapshot pinned to `452b569` on `14 September 2026`.
+
+	## Knowledge-base principles
+
+	1. **The implementation wins.** Runtime code, tests and deployed configuration are authoritative when a prose page conflicts with reality.
+	2. **Implemented and planned behaviour are never mixed.** Roadmaps are labelled as plans; reference pages describe what exists now.
+	3. **Pages are scoped.** Company standards should not contain product-specific implementation details; product pages should link to company standards instead of duplicating them.
+	4. **Operational knowledge is actionable.** Commands, paths, validation steps and rollback behaviour should be documented where people need them.
+	5. **Changes are reviewable.** OtterWiki's Git-backed history is part of the documentation workflow, not merely a backup.
+
+	See [[Company/Wiki-Governance]] for the maintenance model.
/dev/null .. products/index.md
@@ 0,0 1,9 @@
+	# Products
+
+	Product documentation is grouped by product family so implementation detail does not leak into company-wide standards.
+
+	## Current families
+
+	- [[Products/Voxel-Horizons/Index]] — Minecraft/content platform projects.
+
+	When adding another Soatrix product family, create a new directory beneath `products/`, add an index page, then register it here and in [[Company/Service-Catalogue]].
/dev/null .. products/voxel-horizons/index.md
@@ 0,0 1,13 @@
+	# Voxel Horizons
+
+	This section contains technical documentation for the Voxel Horizons software ecosystem.
+
+	## Components
+
+	### VoxelCore
+
+	VoxelCore is the version-aware content foundation currently being rebuilt to provide a stable, data-driven base for Voxel Horizons gameplay systems.
+
+	- [[Products/Voxel-Horizons/VoxelCore/Index]]
+	- [[Products/Voxel-Horizons/VoxelCore/Current-Status]]
+	- [[Products/Voxel-Horizons/VoxelCore/Roadmap-and-Scope]]
/dev/null .. products/voxel-horizons/voxelcore/architecture.md
@@ 0,0 1,53 @@
+	# Architecture
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	VoxelCore separates **authoring**, **compiled definitions**, **render allocation**, **runtime publication** and **platform adaptation**. That separation is the central design decision of the current rebuild.
+
+	```mermaid
+	flowchart TD
+	A[Content pack files] --> B[ContentPackDiscovery]
+	B --> C[ContentLoader + ItemDefinitionParser]
+	C --> D[ItemInheritanceResolver]
+	D --> E[ItemDefinitionCompiler]
+	E --> F[Immutable ItemDefinitionRegistry]
+	F --> G[RenderAllocationRegistry reconcile]
+	G --> H[Platform preflight validation]
+	H --> I[Atomic ContentSnapshot]
+	I --> J[ItemManager]
+	J --> K[VersionAdapter / ItemPlatformAdapter]
+	K --> L[Minecraft ItemStack]
+	F --> M[JavaPackCompiler]
+	G --> M
+	M --> N[Deterministic resource-pack ZIP]
+	```
+
+	## Stable identity
+
+	`ContentID` is the gameplay identity. It is namespaced, normalised and independent of:
+
+	- model path;
+	- numeric Custom Model Data;
+	- structured Custom Model Data indices;
+	- generated pack files.
+
+	That allows rendering schemes to change across Minecraft generations without changing the identity consumed by gameplay code.
+
+	## Immutable publication
+
+	Authored YAML is not retained as mutable runtime truth. The loader compiles it into immutable definitions, reconciles render allocations, validates them against the active platform, then publishes a complete `ContentSnapshot` through the runtime. Reload creates a candidate snapshot separately and only replaces current state after validation succeeds.
+
+	## Adapter boundary
+
+	Common code depends on `VersionAdapter`/`ItemPlatformAdapter` rather than embedding all server-version details in item definitions. Version modules provide their implementation through `PlatformProvider` service registration.
+
+	## Pack compiler boundary
+
+	`voxelcore-pack` consumes the same definitions and render allocation authority used by runtime item creation. This avoids a class of bugs where generated assets and server-side item metadata allocate different render identifiers.
+
+	## Current module shape
+
+	See [[Products/Voxel-Horizons/VoxelCore/Module-Reference]]. The current repository has common, pack, plugin and six version/distribution modules, including exact Minecraft/Paper 26.2 support.
/dev/null .. products/voxel-horizons/voxelcore/build-ci-and-release.md
@@ 0,0 1,58 @@
+	# Build, CI and Release
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	## Maven reactor
+
+	Build all distribution artifacts:
+
+	```bash
+	mvn -U clean package
+	```
+
+	Build one family plus required modules:
+
+	```bash
+	mvn -pl voxelcore-v1_19_4 -am clean package
+	```
+
+	## Java release targets
+
+	The root defaults to Maven `release=8`; newer modules override it:
+
+	- v1.12 and v1.14 families: Java 8 bytecode;
+	- v1.19.4 family: Java 17;
+	- v1.20.5 and v1.21.4 families: Java 21;
+	- v26.2: Java 25.
+
+	CI itself sets up JDK 25 so Maven can compile all of those modules in one reactor. The Shade plugin is `3.6.2`, which supports the Java 25 build path used by the newest module.
+
+	## Distribution packaging
+
+	Each version module shades the common/plugin implementation and relocates SnakeYAML to `org.voxelhorizons.shaded.snakeyaml` to avoid collisions with YAML libraries supplied by old server platforms.
+
+	Representative final names:
+
+	```text
+	VoxelCore-<version>-mc1.12-1.13.jar
+	VoxelCore-<version>-mc1.14-1.19.3.jar
+	VoxelCore-<version>-mc1.19.4-1.20.4.jar
+	VoxelCore-<version>-mc1.20.5-1.21.3.jar
+	VoxelCore-<version>-mc1.21.4.jar
+	VoxelCore-<version>-mc26.2.jar
+	```
+
+	## CI workflows
+
+	The repository contains:
+
+	- `.github/workflows/build.yml` — builds all distributions and publishes/upload artifacts;
+	- `.github/workflows/mvp-smoke.yml` — live-server compatibility matrix;
+	- `.github/scripts/mvp-smoke.sh` — behaviour assertions inside each smoke environment.
+
+	The current smoke matrix has seven rows and uses Java 25/Paper for Minecraft 26.2 alongside the older Java/runtime combinations.
+
+	See [[Products/Voxel-Horizons/VoxelCore/Testing]] for what the matrix proves.
/dev/null .. products/voxel-horizons/voxelcore/commands-and-permissions.md
@@ 0,0 1,93 @@
+	# Commands and Permissions
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	The base Bukkit command is:
+
+	```text
+	/voxelcore
+	```
+
+	with alias:
+
+	```text
+	/vc
+	```
+
+	The base command requires `voxelcore.use`. All currently declared permissions default to server operators. `admin` also has the alias `a`.
+
+	## Administrative reload
+
+	```text
+	/voxelcore admin reload
+	/voxelcore admin rl
+	```
+
+	This calls the same atomic content reload path and requires `voxelcore.admin.reload`.
+
+	## Content
+
+	```text
+	/voxelcore admin content info
+	/voxelcore admin content reload
+	/voxelcore admin content rl
+	```
+
+	Permissions:
+
+	- `voxelcore.admin.content`
+	- `voxelcore.admin.content.info`
+	- `voxelcore.admin.content.reload`
+
+	## Items
+
+	```text
+	/voxelcore admin item list
+	/voxelcore admin item info <content-id>
+	/voxelcore admin item give <content-id> [amount] [player]
+	/voxelcore admin item identify
+	/voxelcore admin item id
+	/voxelcore admin item verify <content-id>
+	/voxelcore admin item test <content-id>
+	```
+
+	`items` is an alias of the `item` command group. `id` aliases `identify`; `test` aliases `verify`.
+
+	Permissions:
+
+	- `voxelcore.admin.item`
+	- `voxelcore.admin.item.list`
+	- `voxelcore.admin.item.info`
+	- `voxelcore.admin.item.give`
+	- `voxelcore.admin.item.identify`
+	- `voxelcore.admin.item.verify`
+
+	Important current behaviour: `item list` filters the compiled registry to definitions whose `bound` value is `true`, then sorts their ContentIDs deterministically. `item info` can still inspect a known unbound definition by ID.
+
+	`give` restricts amount to 1–64. Console callers must supply a valid player; player callers default the target to themselves.
+
+	`identify` is player-only because it inspects the main-hand item. `verify` is console-safe and performs a create → persisted identity round trip.
+
+	## Resource packs
+
+	```text
+	/voxelcore admin pack info
+	/voxelcore admin pack validate [target]
+	/voxelcore admin pack build [target]
+	```
+
+	Permissions:
+
+	- `voxelcore.admin.pack`
+	- `voxelcore.admin.pack.info`
+	- `voxelcore.admin.pack.validate`
+	- `voxelcore.admin.pack.build`
+
+	Known targets are listed in [[Products/Voxel-Horizons/VoxelCore/Resource-Pack-Compiler]].
+
+	## Administrative root
+
+	`voxelcore.admin` protects the `admin`/`a` command group. Child commands then require their more specific permissions described above.
/dev/null .. products/voxel-horizons/voxelcore/configuration.md
@@ 0,0 1,32 @@
+	# Configuration
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	The bundled configuration schema is currently version `1`:
+
+	```yaml
+	version: 1 # DO NOT CHANGE
+	game:
+	bedrock_support: false
+	```
+
+	## `version`
+
+	`version` is managed by VoxelCore and should not be manually changed. At startup VoxelCore compares the current file with the bundled schema version.
+
+	When the schema changes or the version is missing, VoxelCore:
+
+	1. creates an incremental backup (`config.yml.old`, then `.old.1`, `.old.2`, ...);
+	2. merges newly introduced defaults;
+	3. preserves existing user values;
+	4. writes the new schema version;
+	5. reloads the configuration.
+
+	This is intentionally non-destructive; current migration logic does not replace an operator's whole configuration merely because a schema version changed.
+
+	## `game.bedrock_support`
+
+	This setting exists as a future integration point. Setting it to `true` **does not currently implement Bedrock support** in the item/content MVP. Bedrock/Geyser presentation and mappings remain roadmap work.
/dev/null .. products/voxel-horizons/voxelcore/content-packs.md
@@ 0,0 1,72 @@
+	# Content Packs
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	VoxelCore discovers self-contained content packs under `plugins/VoxelCore/content/`.
+
+	## Layout
+
+	```text
+	plugins/VoxelCore/content/
+	└── <pack-directory>/
+	├── pack.yml
+	├── content/
+	│ └── **/*.yml
+	└── assets/
+	└── <namespace>/
+	├── models/
+	├── textures/
+	├── font/
+	└── sounds/
+	```
+
+	The pack directory name is organisational. Identity comes from the manifest namespace and keys in the content files.
+
+	`content/` is scanned recursively for `.yml`/`.yaml` definitions in deterministic order, so authors can create arbitrarily useful nested organisational folders without changing ContentIDs.
+
+	## `pack.yml`
+
+	```yaml
+	schema: 1
+	namespace: mypack
+	dependencies:
+	- shared
+	- core
+	```
+
+	Supported manifest keys are `schema`, `namespace`, and optional `dependencies`. Unknown or malformed keys are rejected rather than silently ignored.
+
+	## Namespaces and dependencies
+
+	Each pack namespace must be unique. A pack may always reference:
+
+	- its own namespace;
+	- Minecraft resources where valid.
+
+	A cross-pack parent or model reference requires the referenced namespace to be declared in `dependencies`. Missing dependencies and duplicate namespaces fail loading.
+
+	## YAML safety and strictness
+
+	The loader uses bounded SnakeYAML parsing, rejects duplicate YAML keys, applies alias/document limits, validates expected scalar/list/map types, and rejects unknown top-level/item/render fields. This deliberately turns authoring mistakes into actionable load errors instead of ignored configuration.
+
+	## Assets
+
+	Authored assets live beneath the pack's namespace. For example:
+
+	```yaml
+	render:
+	model: mypack:item/ruby
+	```
+
+	maps to:
+
+	```text
+	assets/mypack/models/item/ruby.json
+	```
+
+	Generated Minecraft override/item-definition glue belongs to compiler output, not authored content.
+
+	Continue with [[Products/Voxel-Horizons/VoxelCore/Item-Authoring]] and [[Products/Voxel-Horizons/VoxelCore/Rendering-and-Models]].
/dev/null .. products/voxel-horizons/voxelcore/current-status.md
@@ 0,0 1,68 @@
+	# VoxelCore Current Status
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	## Snapshot
+
+	This documentation was reconciled against the repository tree, merged pull requests and implementation on **14 September 2026**. The baseline commit is **`452b569`**, which is the merge of PR #16, *Hide unbound definitions from the item list*.
+
+	The two newest merged changes materially affect the public contract:
+
+	- **PR #16 — unbound list filtering:** `/voxelcore admin item list` now includes only definitions whose compiled `bound` value is `true`. Unbound base/inheritance definitions remain in the registry and can still be inspected/referenced; they are simply omitted from that user-facing list.
+	- **PR #15 — Minecraft/Paper 26.2:** VoxelCore now has a dedicated `voxelcore-v26_2` distribution, exact 26.2 platform adapter, Java 25 compile target, `mc-26.2` resource-pack target with format `88.0`, modern range metadata, and a seventh live-server smoke row.
+
+	## MVP acceptance surface
+
+	Implemented and tested now:
+
+	```text
+	content packs + assets
+	↓
+	deterministic discovery + bounded YAML parsing
+	↓
+	strict schema validation
+	↓
+	single-parent inheritance + compilation
+	↓
+	immutable ItemDefinitionRegistry
+	↓
+	stable render-allocation reconciliation
+	↓
+	platform preflight validation
+	↓
+	atomic ContentSnapshot publication
+	↓
+	ItemManager + version adapter
+	↓
+	ItemStack with persistent ContentID
+
+	same definitions + allocation authority
+	↓
+	deterministic Java resource-pack compiler
+	```
+
+	## Validated live-server matrix
+
+	The smoke matrix now covers **seven** exact versions: 1.12.2, 1.13.2, 1.14.4, 1.19.4, 1.20.5, 1.21.4 and 26.2. See [[Products/Voxel-Horizons/VoxelCore/Version-Support]].
+
+	## Documentation discrepancy to be aware of
+
+	At this snapshot, the repository `README.md` was synchronised by PR #14 **before** PR #15 added 26.2. Its version-family and resource-pack-target tables therefore stop at 1.21.4. The code, Maven reactor, CI changes and merged PR #15 establish 26.2 support; this wiki reflects that newer state.
+
+	## Not implemented as part of this MVP
+
+	- placed custom-block lifecycle;
+	- furniture/display placement lifecycle;
+	- vehicles;
+	- crops;
+	- GUI/menu framework and Bedrock-specific presentation;
+	- Geyser/Floodgate item mappings;
+	- true Minecraft combat `AttributeModifier` authoring;
+	- richer typed metadata for potions, skulls, books, maps and fireworks;
+	- generic low-level post-1.20.5 component escape hatches;
+	- HavenCore compatibility/import aliases.
+
+	These belong to [[Products/Voxel-Horizons/VoxelCore/Roadmap-and-Scope]], not the current supported contract.
/dev/null .. products/voxel-horizons/voxelcore/getting-started.md
@@ 0,0 1,74 @@
+	# Getting Started
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	## Choose the correct distribution
+
+	Install **one** VoxelCore distribution JAR for the server's compatibility family. Do not install multiple family JARs simultaneously. See [[Products/Voxel-Horizons/VoxelCore/Version-Support]] for the exact mapping.
+
+	## Build from source
+
+	The repository is a Maven reactor. Build all distributions with:
+
+	```bash
+	mvn -U clean package
+	```
+
+	A targeted build includes dependent modules with `-am`, for example:
+
+	```bash
+	mvn -pl voxelcore-v1_21_4 -am clean package
+	```
+
+	For the 26.2 distribution:
+
+	```bash
+	mvn -pl voxelcore-v26_2 -am clean package
+	```
+
+	The current CI build environment uses JDK 25 so it can compile the Java 25 module while Maven `release` settings preserve the lower bytecode targets of older modules.
+
+	## First startup
+
+	Place the appropriate shaded JAR in the server's `plugins/` directory and start the server. VoxelCore creates/uses:
+
+	```text
+	plugins/VoxelCore/
+	├── config.yml
+	├── render-allocations.yml
+	├── content/
+	└── build/
+	└── resource-packs/
+	```
+
+	An empty `content/` directory is valid. If authored content is present but fails loading or platform validation, plugin enable is aborted rather than publishing partial state.
+
+	## Readiness marker
+
+	Successful initialisation ends with a log line in this form:
+
+	```text
+	VOXELCORE_READY revision=1 items=<count> platform=<version>
+	```
+
+	CI uses this readiness point rather than treating an early plugin-enable message as success.
+
+	## Add a content pack
+
+	Create a self-contained pack below `plugins/VoxelCore/content/`:
+
+	```text
+	plugins/VoxelCore/content/example/
+	├── pack.yml
+	├── content/
+	│ └── items.yml
+	└── assets/
+	└── example/
+	├── models/item/
+	└── textures/item/
+	```
+
+	Continue with [[Products/Voxel-Horizons/VoxelCore/Content-Packs]] and [[Products/Voxel-Horizons/VoxelCore/Item-Authoring]].
/dev/null .. products/voxel-horizons/voxelcore/index.md
@@ 0,0 1,46 @@
+	# VoxelCore
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	VoxelCore is the version-aware content foundation for Voxel Horizons. The current implemented milestone is the **custom item/content MVP**: deterministic content-pack loading, validated inheritance, immutable runtime snapshots, stable item identity, version-specific `ItemStack` creation, stable render allocation, deterministic Java resource-pack compilation and safe atomic reloads.
+
+	It is intentionally **not yet** the full historical HavenCore feature set. Placed blocks, furniture, vehicles, crops, GUI/menu presentation, Bedrock/Geyser mappings and the broader legacy migration remain later systems.
+
+	## Documentation map
+
+	### Operate VoxelCore
+
+	- [[Products/Voxel-Horizons/VoxelCore/Getting-Started]]
+	- [[Products/Voxel-Horizons/VoxelCore/Configuration]]
+	- [[Products/Voxel-Horizons/VoxelCore/Commands-and-Permissions]]
+	- [[Products/Voxel-Horizons/VoxelCore/Operations-and-Troubleshooting]]
+
+	### Author content
+
+	- [[Products/Voxel-Horizons/VoxelCore/Content-Packs]]
+	- [[Products/Voxel-Horizons/VoxelCore/Item-Authoring]]
+	- [[Products/Voxel-Horizons/VoxelCore/Inheritance]]
+	- [[Products/Voxel-Horizons/VoxelCore/Rendering-and-Models]]
+	- [[Products/Voxel-Horizons/VoxelCore/Resource-Pack-Compiler]]
+
+	### Develop VoxelCore
+
+	- [[Products/Voxel-Horizons/VoxelCore/Architecture]]
+	- [[Products/Voxel-Horizons/VoxelCore/Module-Reference]]
+	- [[Products/Voxel-Horizons/VoxelCore/Version-Support]]
+	- [[Products/Voxel-Horizons/VoxelCore/Runtime-and-Reloads]]
+	- [[Products/Voxel-Horizons/VoxelCore/Build-CI-and-Release]]
+	- [[Products/Voxel-Horizons/VoxelCore/Testing]]
+	- [[Products/Voxel-Horizons/VoxelCore/Source-Reference]]
+
+	### Status and future work
+
+	- [[Products/Voxel-Horizons/VoxelCore/Current-Status]]
+	- [[Products/Voxel-Horizons/VoxelCore/Roadmap-and-Scope]]
+
+	## Core invariant
+
+	A VoxelCore item is identified by its namespaced **ContentID**, not by its model path or Custom Model Data value. Rendering is version-specific presentation state layered over stable gameplay identity.
/dev/null .. products/voxel-horizons/voxelcore/inheritance.md
@@ 0,0 1,43 @@
+	# Inheritance
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	VoxelCore compiles single-parent inheritance before content is published.
+
+	## Parent references
+
+	Within the same namespace, a local parent key can be used. Cross-pack references are valid only when the parent namespace is declared as a pack dependency.
+
+	## Current merge semantics
+
+	| Value | Behaviour |
+	|---|---|
+	| omitted scalar | inherit parent value |
+	| provided scalar | replace parent value |
+	| explicit `false` | replaces inherited `true` |
+	| list | explicitly supplied child list replaces parent list |
+	| `properties` map | recursive deep merge |
+	| render metadata | field-by-field merge |
+	| structured `custom_model_data` | semantic-key merge when parent and child are both structured |
+	| switch numeric ↔ structured CMD | child representation replaces parent representation |
+
+	Only one parent is supported per item.
+
+	## Validation
+
+	Compilation rejects:
+
+	- missing parents;
+	- self-cycles or longer inheritance cycles;
+	- duplicate ContentIDs;
+	- definitions that remain invalid after resolution, such as missing required material;
+	- illegal cross-pack references without declared dependencies.
+
+	The resolver includes dependency-chain context in compilation errors so invalid authoring fails at load/reload time rather than surfacing as a gameplay error later.
+
+	## Base definitions and list visibility
+
+	A definition can remain `bound: false` and serve only as an inheritance base. It still participates in compilation and the runtime registry, but current `/voxelcore admin item list` filtering hides it from the user-facing list.
/dev/null .. products/voxel-horizons/voxelcore/item-authoring.md
@@ 0,0 1,70 @@
+	# Item Authoring
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	Items are declared below an `items:` mapping in any YAML file beneath a pack's `content/` directory.
+
+	```yaml
+	items:
+	gem_base:
+	material: minecraft:paper
+	bound: false
+	lore:
+	- A VoxelCore item
+
+	ruby:
+	extends: gem_base
+	display_name: Ruby
+	bound: true
+	render:
+	model: mypack:item/ruby
+	unbreakable: true
+	durability: 0
+	attributes:
+	hide_attributes: true
+	custom_model_data: 1001
+	properties:
+	category: gemstone
+	```
+
+	## Supported fields
+
+	The current item schema accepts:
+
+	- `extends`
+	- `type`
+	- `material`
+	- `display_name`
+	- `lore`
+	- `bound`
+	- `render`
+	- `properties`
+
+	Unknown keys are errors.
+
+	## ContentID
+
+	The key is combined with the pack namespace to form a stable ID:
+
+	```text
+	mypack:ruby
+	```
+
+	IDs are normalised to lowercase and namespace/value segments use `[a-z0-9._-]+`. File paths do not become part of the ID.
+
+	## `bound`
+
+	`bound` is a compiled boolean field and defaults to `false` when it is not supplied/inherited. As of PR #16, `/voxelcore admin item list` only shows definitions with `bound: true`. This makes `bound: false` useful for inheritance-only/base definitions without losing them from the compiled registry.
+
+	Do not infer more from this flag than the implementation guarantees: unbound definitions still exist in the registry and can be referenced/inspected.
+
+	## `properties`
+
+	`properties` is a structured author-owned map. Parent/child maps deep-merge and compiled nested structures are deep-frozen so runtime definitions do not expose mutable nested state.
+
+	## Rendering fields
+
+	Rendering is deliberately separate from ContentID and is covered in [[Products/Voxel-Horizons/VoxelCore/Rendering-and-Models]].
/dev/null .. products/voxel-horizons/voxelcore/module-reference.md
@@ 0,0 1,40 @@
+	# Module Reference
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	The root Maven reactor currently contains nine modules.
+
+	| Module | Responsibility |
+	|---|---|
+	| `voxelcore-common` | Content IDs, authoring models, parsing/compilation, runtime snapshots, render allocations, common item/platform contracts. |
+	| `voxelcore-pack` | Deterministic Java resource-pack compilation and exact pack-target profiles. |
+	| `voxelcore-plugin` | Bukkit plugin lifecycle, configuration migration, command framework, `PackManager`, platform discovery. |
+	| `voxelcore-v1_12` | 1.12.x–1.13.x legacy family, legacy NBT identity and distribution packaging. |
+	| `voxelcore-v1_14` | 1.14–1.19.3 family, PDC/numeric CMD path and distribution packaging. |
+	| `voxelcore-v1_19_4` | 1.19.4–1.20.4 family boundary. |
+	| `voxelcore-v1_20_5` | 1.20.5–1.21.3 data-component-era family. |
+	| `voxelcore-v1_21_4` | Exact 1.21.4 structured CMD/item-model implementation. |
+	| `voxelcore-v26_2` | Exact 26.2 Paper implementation compiled with Java 25. |
+
+	## `voxelcore-common` package map
+
+	- `content.ContentID` — canonical namespaced identity.
+	- `content.load.*` — deterministic pack/file loading and strict YAML parsing.
+	- `content.compile.*` — inheritance resolution and compilation.
+	- `content.item.*` — raw and compiled item models.
+	- `content.render.*` — persistent render allocation registry/store and structured indices.
+	- `content.runtime.*` — snapshot publication and safe reload result/runtime.
+	- `item.ItemManager` — definition lookup, item creation and identity lookup through the active snapshot.
+	- `platform.*` — version, capabilities, provider/adapter contracts.
+	- `platform.item.*` — item platform adapter and metadata flag support.
+
+	## `voxelcore-plugin`
+
+	The plugin module wires the pieces together in `org.voxelhorizons.VoxelCore`. Startup performs config migration, platform selection, content load, allocation reconciliation, platform validation, snapshot publication, manager construction and command registration before emitting `VOXELCORE_READY`.
+
+	## Version module service discovery
+
+	Each version module registers an `org.voxelhorizons.platform.PlatformProvider` in `META-INF/services`. This keeps version-specific classes isolated from common code and lets `VersionAdapterFactory` select a matching provider at runtime.
/dev/null .. products/voxel-horizons/voxelcore/operations-and-troubleshooting.md
@@ 0,0 1,80 @@
+	# Operations and Troubleshooting
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	## Plugin will not enable
+
+	Check the first `SEVERE` VoxelCore error, not only the final disable line. Startup intentionally aborts for unsupported platforms, malformed content, failed inheritance, invalid render allocation state or platform preflight failure.
+
+	Expected successful endpoint:
+
+	```text
+	VOXELCORE_READY revision=1 items=<count> platform=<version>
+	```
+
+	### Unsupported Minecraft version
+
+	VoxelCore selects a platform provider explicitly. Exact-only providers such as 1.21.4 and 26.2 reject other releases. Install the correct distribution and do not assume a newer server is compatible merely because it starts with a similar API.
+
+	## Reload fails
+
+	Use:
+
+	```text
+	/voxelcore admin content reload
+	```
+
+	A failed reload is designed to leave the previous revision active. Fix the reported authoring/platform error and reload again; do **not** delete known-good runtime files as a first response.
+
+	Common causes include missing parents, cycles, undeclared cross-pack dependencies, missing/invalid model references, malformed structured model keys and definitions that cannot be represented by the active adapter.
+
+	## Item is missing from `item list`
+
+	Check the compiled `bound` value with:
+
+	```text
+	/voxelcore admin item info <content-id>
+	```
+
+	As of PR #16, unbound definitions are intentionally omitted from `item list`. This is expected for inheritance-only bases.
+
+	## Item does not identify
+
+	Use the held-item command for a player:
+
+	```text
+	/voxelcore admin item identify
+	```
+
+	or the console-safe round-trip test:
+
+	```text
+	/voxelcore admin item verify <content-id>
+	```
+
+	The verify success marker is:
+
+	```text
+	VOXELCORE_ITEM_VERIFY_OK ...
+	```
+
+	Stored malformed/corrupt ContentID metadata is handled defensively and should not crash ordinary identification.
+
+	## Pack target not auto-selected
+
+	Pack commands auto-select only for an exact `JavaPackTarget`. Specify one explicitly, for example:
+
+	```text
+	/voxelcore admin pack validate mc-26.2
+	```
+
+	## Rendering changes unexpectedly after deleting allocations
+
+	`render-allocations.yml` is persistent allocation history. Removing it can reassign numeric CMD or structured indices. Restore the manifest from backup/versioned server data where possible rather than treating it as disposable cache.
+
+	## Config migrated
+
+	Look for `config.yml.old`, `.old.1`, etc. Current migration preserves existing values and adds new defaults. Do not copy an old schema version back over the migrated file without understanding the change.
/dev/null .. products/voxel-horizons/voxelcore/rendering-and-models.md
@@ 0,0 1,91 @@
+	# Rendering and Models
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	Rendering metadata is **presentation state**, not item identity. A ContentID should remain stable even when its model, Custom Model Data allocation or client representation changes.
+
+	## Common render metadata
+
+	```yaml
+	render:
+	model: mypack:item/ruby
+	unbreakable: true
+	durability: 4
+	attributes:
+	hide_attributes: true
+	custom_model_data: 1001
+	```
+
+	### Durability and CMD are independent
+
+	`render.durability` is not an alias for Custom Model Data. For 1.12/1.13 legacy pack generation, explicit durability drives damage predicates. Runtime Custom Model Data has no representation on those versions and is ignored there rather than being repurposed.
+
+	### Item flags
+
+	`render.attributes` currently maps author-facing keys to Bukkit `ItemFlag` values; it is **not** the future combat `AttributeModifier` system. Names are normalised to enum-style constants and unsupported flags on an older runtime are ignored. Compatibility aliases remain for historically different Bukkit names such as enchantment/destroyable/placeable hiding.
+
+	## Structured Custom Model Data
+
+	Minecraft 1.21.4 and 26.2 use the modern item adapter and can represent structured Custom Model Data:
+
+	```yaml
+	render:
+	model: mypack:item/ruby
+	custom_model_data:
+	variant: red
+	powered: true
+	intensity: 0.75
+	tint: '#ff0000'
+	```
+
+	Value type inference:
+
+	| YAML value | Allocated component kind |
+	|---|---|
+	| number | float |
+	| boolean | flag |
+	| ordinary string | string |
+	| `#RRGGBB` | color |
+
+	VoxelCore stores stable semantic-key → typed-index allocation in `render-allocations.yml`; authors do not manually manage list indices.
+
+	## Modern render rules
+
+	`render.rule` defines the generated modern item-model decision graph. Supported node types are `select`, `condition`, `range` and `model`.
+
+	```yaml
+	render:
+	model: mypack:item/ruby
+	custom_model_data:
+	variant: red
+	powered: true
+	intensity: 0.75
+	tint: '#ff0000'
+	rule:
+	select:
+	key: variant
+	cases:
+	red:
+	condition:
+	key: powered
+	true:
+	range:
+	key: intensity
+	entries:
+	0.75:
+	model:
+	id: mypack:item/ruby_powered
+	tint: tint
+	fallback: mypack:item/ruby
+	false: mypack:item/ruby
+	fallback: mypack:item/ruby
+	```
+
+	Pre-1.21.4 pack targets reject `render.rule` instead of silently discarding it.
+
+	## Asset resolution
+
+	`mypack:item/ruby` resolves to `assets/mypack/models/item/ruby.json`. A texture reference with the same logical path resolves beneath `assets/mypack/textures/item/ruby.png`. Cross-pack model references are dependency checked.
/dev/null .. products/voxel-horizons/voxelcore/resource-pack-compiler.md
@@ 0,0 1,51 @@
+	# Resource Pack Compiler
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	`voxelcore-pack` compiles authored assets plus the active render-allocation authority into deterministic Java resource-pack ZIP files.
+
+	## Exact pack targets
+
+	| Target | Mode | Pack metadata format |
+	|---|---|---:|
+	| `mc-1.12.2` | legacy durability/damage predicate | 3 |
+	| `mc-1.13.2` | legacy durability/damage predicate | 4 |
+	| `mc-1.14.4` | numeric Custom Model Data | 4 |
+	| `mc-1.19.4` | numeric Custom Model Data | 13 |
+	| `mc-1.20.5` | numeric Custom Model Data | 32 |
+	| `mc-1.21.4` | modern item-model / structured CMD | 46 |
+	| `mc-26.2` | modern item-model / structured CMD | **88.0** |
+
+	The 26.2 target uses modern `pack.mcmeta` range metadata (`min_format` and `max_format`) rather than the legacy `pack_format` shape used by older targets.
+
+	## Build output
+
+	Runtime pack builds are written to:
+
+	```text
+	plugins/VoxelCore/build/resource-packs/<target>.zip
+	```
+
+	Use:
+
+	```text
+	/voxelcore admin pack validate [target]
+	/voxelcore admin pack build [target]
+	```
+
+	If the target is omitted, VoxelCore only auto-selects when the current server version has an **exact** registered pack target. Otherwise the command asks for an explicit target.
+
+	## Determinism
+
+	The compiler writes sorted entries with fixed ZIP metadata so identical authoring + allocation state produces identical archive bytes. This improves reproducibility and makes generated differences meaningful.
+
+	## Shared allocation authority
+
+	Runtime item creation and pack compilation both use `render-allocations.yml`. Numeric CMD values and structured semantic-key indices therefore cannot independently drift between server-side stacks and the generated pack.
+
+	## Asset validation
+
+	Compiler validation checks model ownership/dependencies and required authored model assets. Generated Minecraft glue is written to build output; it is not expected to be manually authored inside a content pack.
/dev/null .. products/voxel-horizons/voxelcore/roadmap-and-scope.md
@@ 0,0 1,57 @@
+	# Roadmap and Scope
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	This page separates what the wider VoxelCore rebuild **plans** to become from what the current item/content MVP already supports.
+
+	## Current completed foundation
+
+	The present implementation has realised several early roadmap principles:
+
+	- deterministic content discovery and bounded YAML parsing;
+	- explicit single-parent inheritance with cycle/missing-parent validation;
+	- immutable compiled definitions;
+	- atomic runtime snapshot publication and failed-reload preservation;
+	- stable ContentID separate from rendering identifiers;
+	- shared persistent render-allocation authority;
+	- deterministic Java resource-pack compilation;
+	- explicit version adapters and exact pack profiles;
+	- real-server CI behaviour checks instead of enable-line-only CI;
+	- non-destructive config schema migration.
+
+	## Next system classes
+
+	The broader migration roadmap still calls for systems beyond this MVP. Current README/source explicitly leaves these outside the supported item milestone:
+
+	- placed custom blocks;
+	- furniture, seats, storage, light and display-entity lifecycle;
+	- vehicles/input/simulation;
+	- crops and bounded growth scheduling;
+	- GUI/menu framework and session lifecycle;
+	- Bedrock/Geyser frontend mappings and presentation;
+	- richer version-aware item metadata;
+	- legacy HavenCore import/compatibility paths.
+
+	## Architectural direction from the migration roadmap
+
+	The planning document recommends maintaining a distinction between:
+
+	- immutable **content definitions**;
+	- individual **item instance state**;
+	- persistent **world placement state**;
+	- replaceable **render handles**.
+
+	It also proposes keeping gameplay addons dependent on stable services/API contracts rather than importing one another's mutable registries, and treating the pack builder as a deterministic compiler rather than a ZIP utility.
+
+	These are planning constraints and design direction, not a claim that all proposed modules/services already exist in `main`.
+
+	## Compatibility policy
+
+	The roadmap's most important rule is already visible in implementation: compatibility must be explicit. 1.21.4 no longer claims unvalidated future versions, and Minecraft/Paper 26.2 received a dedicated adapter, Java target, pack profile and smoke row. Future releases should follow that pattern.
+
+	## Documentation rule for future milestones
+
+	When a roadmap item is merged, move its behavioural contract into dedicated reference pages and remove it from the “not implemented” list. Do not make this roadmap page the only documentation for a completed subsystem.
/dev/null .. products/voxel-horizons/voxelcore/runtime-and-reloads.md
@@ 0,0 1,51 @@
+	# Runtime and Reloads
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	Reload is transactional at the content-snapshot level. VoxelCore does not clear the live registry and then hope replacement content succeeds.
+
+	## Startup
+
+	Startup performs, in order:
+
+	1. configuration generation/migration;
+	2. platform adapter selection;
+	3. content-directory creation and deterministic load;
+	4. inheritance compilation;
+	5. render-allocation load/reconciliation;
+	6. validation of every compiled definition through the selected platform item adapter;
+	7. persistence of validated allocations;
+	8. publication of content revision `1`;
+	9. `ItemManager`/`PackManager` construction;
+	10. command registration;
+	11. `VOXELCORE_READY` logging.
+
+	A load or platform-validation failure disables the plugin before publishing a usable runtime.
+
+	## Reload
+
+	```mermaid
+	flowchart TD
+	A[Active revision N] --> B[Load candidate files]
+	B --> C[Compile candidate registry]
+	C --> D[Reconcile candidate allocations]
+	D --> E[Platform preflight]
+	E -->|success| F[Persist allocation state]
+	F --> G[Atomically publish revision N+1]
+	B -->|failure| H[Discard candidate]
+	C -->|failure| H
+	D -->|failure| H
+	E -->|failure| H
+	H --> I[Revision N remains active]
+	```
+
+	`ContentRuntime` publishes immutable `ContentSnapshot` objects. `ItemManager` resolves through the active runtime, so existing manager references observe the new snapshot after successful publication.
+
+	## Allocation persistence
+
+	`render-allocations.yml` is persisted only after candidate definitions are validated for the active platform. Tombstones preserve removed numeric allocations and structured keys remain reserved, avoiding silent re-use.
+
+	Do not casually delete `render-allocations.yml` on a live content set; doing so discards allocation history and can change rendering identifiers.
/dev/null .. products/voxel-horizons/voxelcore/source-reference.md
@@ 0,0 1,46 @@
+	# Source Reference
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	Use these locations when the wiki and implementation need to be reconciled.
+
+	## Repository documents
+
+	- [`README.md`](https://github.com/VoxelHorizons/VoxelCore/blob/main/README.md) — concise operator/author overview; note the 26.2 table lag described in [[Products/Voxel-Horizons/VoxelCore/Current-Status]].
+	- [`Migration-Roadmap.md`](https://github.com/VoxelHorizons/VoxelCore/blob/main/Migration-Roadmap.md) — broader rebuild rationale and planning; planning content is not automatically implemented behaviour.
+	- [`pom.xml`](https://github.com/VoxelHorizons/VoxelCore/blob/main/pom.xml) — current Maven module reactor and shared dependency versions.
+
+	## Common content/runtime
+
+	- [`ContentID.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/ContentID.java)
+	- [`ContentLoader.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/load/ContentLoader.java)
+	- [`ItemDefinitionParser.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/load/ItemDefinitionParser.java)
+	- [`ItemInheritanceResolver.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/compile/ItemInheritanceResolver.java)
+	- [`ItemDefinitionCompiler.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/compile/ItemDefinitionCompiler.java)
+	- [`ContentSnapshot.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/runtime/ContentSnapshot.java)
+	- [`ContentRuntimeReloader.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/runtime/ContentRuntimeReloader.java)
+	- [`RenderAllocationRegistry.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/render/RenderAllocationRegistry.java)
+	- [`RenderAllocationStore.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/content/render/RenderAllocationStore.java)
+	- [`ItemManager.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-common/src/main/java/org/voxelhorizons/item/ItemManager.java)
+
+	## Pack compiler
+
+	- [`JavaPackCompiler.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-pack/src/main/java/org/voxelhorizons/pack/JavaPackCompiler.java)
+	- [`JavaPackCompilerEngine.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-pack/src/main/java/org/voxelhorizons/pack/JavaPackCompilerEngine.java)
+	- [`JavaPackTarget.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-pack/src/main/java/org/voxelhorizons/pack/JavaPackTarget.java)
+
+	## Plugin/runtime wiring
+
+	- [`VoxelCore.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-plugin/src/main/java/org/voxelhorizons/VoxelCore.java)
+	- [`ItemCommand.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-plugin/src/main/java/org/voxelhorizons/command/commands/ItemCommand.java)
+	- [`ContentCommand.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-plugin/src/main/java/org/voxelhorizons/command/commands/ContentCommand.java)
+	- [`PackCommand.java`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-plugin/src/main/java/org/voxelhorizons/command/commands/PackCommand.java)
+	- [`plugin.yml`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-plugin/src/main/resources/plugin.yml)
+	- [`config.yml`](https://github.com/VoxelHorizons/VoxelCore/blob/main/voxelcore-plugin/src/main/resources/config.yml)
+
+	## Compatibility modules
+
+	The version implementations live beneath `voxelcore-v1_12`, `voxelcore-v1_14`, `voxelcore-v1_19_4`, `voxelcore-v1_20_5`, `voxelcore-v1_21_4` and `voxelcore-v26_2`.
/dev/null .. products/voxel-horizons/voxelcore/testing.md
@@ 0,0 1,45 @@
+	# Testing
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	VoxelCore combines focused unit/regression tests with real plugin-capable server smoke tests.
+
+	## Unit/regression coverage
+
+	Current tests cover, among other behaviour:
+
+	- item compilation and multi-level inheritance;
+	- missing parents, cycles, duplicate IDs and required-field validation;
+	- deep immutability of compiled definition data;
+	- YAML loading/discovery and strict schema handling;
+	- stable render allocation and tombstone behaviour;
+	- structured semantic-key typed indices and type-change rejection;
+	- runtime reload rollback and successful publication;
+	- `ItemManager` use of the active snapshot allocation;
+	- platform version parsing, including Paper's build-qualified 26.2 version;
+	- item metadata flag resolution;
+	- deterministic Java pack output and modern rule generation;
+	- 26.2 `min_format`/`max_format` pack metadata;
+	- config migration preserving operator values;
+	- unbound definitions being excluded from `item list`.
+
+	## Real-server matrix
+
+	Validated exact servers:
+
+	1. 1.12.2
+	2. 1.13.2
+	3. 1.14.4
+	4. 1.19.4
+	5. 1.20.5
+	6. 1.21.4
+	7. 26.2
+
+	The smoke path goes beyond “plugin enabled”: it waits for the `VOXELCORE_READY` marker, exercises content/admin behaviour, verifies create → stored ContentID → identify round trips, validates/builds the exact resource-pack target, deliberately triggers a failed reload and confirms the old revision remains active, then restores valid content and confirms a successful new revision.
+
+	## Fixture families
+
+	The repository currently carries `mvp-content`, `mvp-content-legacy` and `mvp-content-modern` fixtures so rendering boundaries can be exercised without pretending one authored render representation behaves identically on every client generation.
/dev/null .. products/voxel-horizons/voxelcore/version-support.md
@@ 0,0 1,27 @@
+	# Version Support
+
+
+	> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.
+	> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
+
+
+	VoxelCore distinguishes a **runtime compatibility family** from an **exact version that is exercised in the real-server smoke matrix**. Do not treat every intermediate version in a family as individually smoke-tested.
+
+	| Minecraft runtime | Module / final JAR family | Java release | Runtime rendering/identity boundary | Exact live validation |
+	|---|---|---:|---|---|
+	| 1.12.x–1.13.x | `voxelcore-v1_12` / `mc1.12-1.13` | 8 | legacy NBT identity; explicit durability legacy rendering | 1.12.2, 1.13.2 |
+	| 1.14–1.19.3 | `voxelcore-v1_14` / `mc1.14-1.19.3` | 8 | PDC identity; numeric Custom Model Data | 1.14.4 |
+	| 1.19.4–1.20.4 | `voxelcore-v1_19_4` / `mc1.19.4-1.20.4` | 17 | PDC/CMD; display-entity-era capability boundary | 1.19.4 |
+	| 1.20.5–1.21.3 | `voxelcore-v1_20_5` / `mc1.20.5-1.21.3` | 21 | data-component era; scalar CMD compatibility | 1.20.5 |
+	| 1.21.4 | `voxelcore-v1_21_4` / `mc1.21.4` | 21 | item-model component + structured CMD | 1.21.4 |
+	| 26.2 | `voxelcore-v26_2` / `mc26.2` | 25 | modern item adapter; Paper 26.2 exact boundary | 26.2 |
+
+	The 1.21.4 and 26.2 providers are deliberately exact. A future Minecraft release must gain an explicit validated adapter instead of being accepted just because its API appears similar.
+
+	## Paper 26.2 notes
+
+	The 26.2 module compiles against Paper API `26.2.build.123-stable`. VoxelCore parses Paper's build-qualified version form such as `26.2.build.123-stable` as Minecraft version `26.2.0` for adapter selection. This is not a general licence to accept arbitrary 26.x releases; the provider matches `26.2.0` exactly.
+
+	## Resource-pack target support
+
+	Runtime families and pack profiles are related but not identical. Pack compilation deliberately exposes only exact validated targets; see [[Products/Voxel-Horizons/VoxelCore/Resource-Pack-Compiler]].
/dev/null .. templates/architecture-decision-record.md
@@ 0,0 1,29 @@
+	# Template — Architecture Decision Record
+
+	**Status:** Proposed / Accepted / Superseded / Rejected
+	**Date:** YYYY-MM-DD
+	**Decision owners:**
+
+	## Context
+
+	What problem, constraint or repeated ambiguity requires a durable decision?
+
+	## Decision
+
+	State the chosen approach precisely.
+
+	## Alternatives considered
+
+	Describe credible alternatives and why they were not selected.
+
+	## Consequences
+
+	Record benefits, trade-offs, compatibility implications, migration cost and operational effects.
+
+	## Follow-up
+
+	Implementation tasks, tests, migration work and documentation that must change.
+
+	## Supersession
+
+	If this ADR replaces or is replaced by another ADR, link both directions.
/dev/null .. templates/incident-review.md
@@ 0,0 1,38 @@
+	# Template — Incident Review
+
+	**Incident date/time:**
+	**Service(s):**
+	**Impact:**
+	**Status:** Resolved / Monitoring / Open
+
+	## Summary
+
+	Short factual description of user-visible impact and duration.
+
+	## Timeline
+
+	Use exact timestamps with time zones. Mark hypotheses as hypotheses.
+
+	## Detection
+
+	How the issue was first detected and whether monitoring should have detected it earlier.
+
+	## Root and contributing conditions
+
+	Explain technical/system conditions without assigning personal blame.
+
+	## Recovery
+
+	What restored service and how restoration was verified.
+
+	## What worked / what did not
+
+	Tools, runbooks, alerts, architecture and communication.
+
+	## Actions
+
+	Concrete owner, action and tracking reference. Separate immediate fixes from longer-term prevention.
+
+	## Documentation changes
+
+	List runbooks/reference pages that were created or updated because of this incident.
/dev/null .. templates/index.md
@@ 0,0 1,9 @@
+	# Templates
+
+	Copy these page structures when adding new products or operational knowledge. Delete sections that genuinely do not apply rather than filling the wiki with placeholder text.
+
+	- [[Templates/Product-Documentation]]
+	- [[Templates/Service-Runbook]]
+	- [[Templates/Architecture-Decision-Record]]
+	- [[Templates/Incident-Review]]
+	- [[Templates/Release-Checklist]]
/dev/null .. templates/product-documentation.md
@@ 0,0 1,35 @@
+	# Template — Product Documentation
+
+	> Copy this structure into a new product directory; this page itself is not a product record.
+
+	## Index
+
+	Purpose, audience, lifecycle status, repository and links to the main reference pages.
+
+	## Current Status
+
+	Baseline branch/commit, verification date, supported surface, newest material changes and known documentation discrepancies.
+
+	## Getting Started
+
+	Smallest repeatable path from zero to a validated working installation/development environment.
+
+	## Architecture
+
+	Boundaries, identity/data model, dependencies and a diagram where useful.
+
+	## Reference
+
+	Configuration, commands/API, persistence/data, authentication/security, compatibility/version support.
+
+	## Operations
+
+	Deployment/release, monitoring, backup/restore, common failures and recovery procedures.
+
+	## Development
+
+	Module map, build/test commands, CI expectations and source-reference links.
+
+	## Roadmap
+
+	Future work clearly labelled as planning, with completed behaviour moved into reference pages.
/dev/null .. templates/release-checklist.md
@@ 0,0 1,34 @@
+	# Template — Release Checklist
+
+	## Scope
+
+	- [ ] Release/version/commit identified.
+	- [ ] User-visible and operator-visible changes summarised.
+	- [ ] Compatibility impact reviewed.
+	- [ ] Configuration/data migrations documented.
+
+	## Validation
+
+	- [ ] Required unit/integration suites pass.
+	- [ ] Runtime/smoke tests pass for claimed compatibility targets.
+	- [ ] Build artifacts correspond to the intended commit.
+	- [ ] Upgrade path tested where applicable.
+
+	## Operations
+
+	- [ ] Backup/rollback boundary understood.
+	- [ ] Required credentials/access available through approved systems.
+	- [ ] Monitoring/health check prepared.
+
+	## Documentation
+
+	- [ ] Current Status page updated.
+	- [ ] Commands/configuration/version tables updated if changed.
+	- [ ] New limitations or migration notes documented.
+	- [ ] Roadmap items moved into reference documentation when completed.
+
+	## Post-release
+
+	- [ ] Deployment verified from the user perspective.
+	- [ ] Logs/metrics checked for regressions.
+	- [ ] Temporary migration notes/toggles scheduled for cleanup if applicable.
/dev/null .. templates/service-runbook.md
@@ 0,0 1,29 @@
+	# Template — Service Runbook
+
+	## Purpose
+
+	What this runbook restores or changes, and when to use it.
+
+	## Preconditions
+
+	Required access, backups, maintenance state and checks before starting. Reference secret locations without copying secrets.
+
+	## Procedure
+
+	Numbered, executable steps. Put commands in code blocks and state expected output/checkpoints.
+
+	## Verification
+
+	How to prove the service is healthy from the user's perspective.
+
+	## Rollback
+
+	Exact safe rollback boundary and data/config implications.
+
+	## Escalation
+
+	Which product/service owner or specialist is required when the procedure does not recover the system.
+
+	## Last validation
+
+	Date and version/environment on which this runbook was actually exercised.