Build mod compatibility foundations

AGENTS.md

@@ -55,6 +55,13 @@ Registration is composed through `RetoldSubsystems` and the classes under `modul
 
 ### Architecture And Ownership
 
+- Design new systems with mod and datapack compatibility in mind from the start. Prefer standard
+  tags when their full meaning matches, Retold-owned semantic tags/data for Retold concepts, and
+  small optional hooks over hard-coded third-party integrations.
+- When materially changing an existing subsystem, audit compatibility assumptions on the touched
+  path and improve them when safe and testable. Do not perform unrelated compatibility rewrites;
+  document and defer unresolved cases. Preserve standalone defaults unless the developer explicitly
+  approves a gameplay change, and regression-test those defaults when adding extension points.
 - Keep gameplay rules in named Retold system classes. Mixins should normally be hooks, guards, accessors, or narrowly scoped vanilla interception points.
 - Route world-stage changes through `RetoldStageManager.setStage` so persistence, synchronization, and transition effects remain consistent.
 - Keep server gameplay state authoritative. Client code should render, present feedback, or consume synchronized state rather than decide progression.

CHANGELOG.md

@@ -30,6 +30,9 @@ Each release should be readable in two passes:
 
 ### Technical
 
+- Added the initial stable `cz.xefensor.retold.api` compatibility surface. `RetoldRecipeKnowledge` now gives vanilla and optional viewers one synchronized per-player visibility authority, keeps unknown custom recipe types visible by default, and lets integrations opt types into discovery with removable registrations. `RetoldWorldProtection` adds default-allow, deny-capable mutation rules with exact affected bounds and now gates Retold-owned mob block changes, Gale Core breaking, Aender regeneration/portals, and delayed structure retrogen. Focused tests cover unchanged standalone behavior, per-player recipe isolation, client payload round trips, custom recipe-type registration, denied mutations, and registration removal; concrete EMI, JEI, and claim-mod adapters remain pending.
+- Completed a behavior-preserving exact item/block compatibility audit. Datapack extension tags now cover environmental mob resources, ordinary forage and dropped-food families, Spider-lair web counting, Illager village signals, Nether-remnant and Ocean-Monument guard anchors, protected monument blocks, consumable Campfire igniters, and leaf-preserving tools. Exact-match vanilla and NeoForge common tags are composed where safe, while Retold's former vanilla memberships remain the defaults. Fixed progression, paired transformation, portal/structure, unique loot/replacement, and unverified Sniffer checks remain exact by design. Added focused registry tests and a modpack-author compatibility reference.
+- Made faction classification data-driven through additive entity-type tags while retaining the fixed Retold relationship matrix. The default tags preserve prior members, compose standard Illager and Undead classifications, and keep Witch-style loose alliance separate; ambiguous full memberships fail closed. Cached membership and faction goals now follow server tag reloads, and focused tests cover defaults, targeting, retaliation, loose allies, conflicts, and tamed undead mounts.
 - Added the 48-durability Flint Multi-tool, Flint Spear, and provisional Steel material with data-driven mining, repair, common-ingot, Spear, enchantment-family, and armor tags. A global loot modifier supplies scaled Sticks from leaves and woody bushes, and placed-feature overrides reduce both ordinary and Dripstone Copper attempts from sixteen to six per chunk. Data-driven chest and Villager-trade overrides enforce fixed acquisition tiers without per-player state, while enchantment tags remove Mending from new trade/random-loot generation. Exact Wooden/Stone recipes are removed during recipe loading; Armorer, Toolsmith, and Weaponsmith lessons follow the material ladder. Focused GameTests cover scaled Stick supply, acquisition tables and prices, Mending source removal, reduced Copper placement, Campfire behavior, harvest tiers, Spear/starter/equipment crafting, station processing, and Furnace availability.
 - Added tag-driven dynamic Diamond durability through a narrow `ItemStack.getMaxDamage` hook and a named progression policy. Diamond Horse and Nautilus Armor receive a 528-durability component and server-side BODY-slot wear from non-bypassing hits. Focused coverage enumerates all twelve enchantable Diamond items and verifies fragile values, enchantment restoration, removal regression, real animal-armor wear, vanilla-tag preservation, and the over-damaged stripped-item safeguard.
 - Added data-driven Chestplate enchantment compatibility and material-matched enchantability components for all twelve vanilla animal armors. A Wolf-specific incoming-damage bridge applies vanilla enchantment protection before Wolf Armor's special durability-absorption path bypasses ordinary living-entity mitigation. Focused coverage verifies every supported-enchantment set plus equipped Protection-family mitigation, Fire Protection burn duration, Thorns, Unbreaking, Mending, Binding, and Vanishing behavior across Wolf, Horse, and Nautilus armor paths.

CONTRIBUTING.md

@@ -26,9 +26,14 @@ The current target is recorded in [`gradle.properties`](gradle.properties). Usef
 
 1. Start from current `master` and create a focused branch.
 2. Keep unrelated formatting and refactors out of the change.
-3. Update tests, documentation, and `CHANGELOG.md` when affected.
-4. Run appropriate validation and describe it honestly.
-5. Open a pull request and complete its template.
+3. Design new systems with mod and datapack compatibility in mind. When materially changing an
+   existing subsystem, audit compatibility assumptions on the touched path and improve them when
+   safe without turning the contribution into an unrelated rewrite.
+4. Preserve Retold's standalone defaults when adding extension points, unless a gameplay change was
+   explicitly agreed, and add focused regression coverage for those defaults.
+5. Update tests, documentation, and `CHANGELOG.md` when affected.
+6. Run appropriate validation and describe it honestly.
+7. Open a pull request and complete its template.
 
 Small changes are easier to verify. A technically sound proposal may still be declined when it conflicts with Retold's design.
 

README.md

@@ -74,6 +74,7 @@ Some systems still need broader real-world validation, especially dimension trav
 
 - [`docs/README.md`](docs/README.md) — documentation index
 - [`docs/design-overview.md`](docs/design-overview.md) — world and gameplay design
+- [`docs/compatibility.md`](docs/compatibility.md) — supported datapack extension tags and integration boundaries
 - [`ROADMAP.md`](ROADMAP.md) — public Now / Next / Later roadmap
 - [`docs/internal/README.md`](docs/internal/README.md) — developer and technical documentation
 - [`docs/internal/retold_mod_system.md`](docs/internal/retold_mod_system.md) — implementation architecture

docs/README.md

@@ -9,6 +9,7 @@ This directory separates player-facing design information from detailed develope
 - [`../CHANGELOG.md`](../CHANGELOG.md) — released and unreleased changes
 - [`../SUPPORT.md`](../SUPPORT.md) — help and problem reporting
 - [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — contribution workflow
+- [`compatibility.md`](compatibility.md) — supported datapack extension tags and integration boundaries
 
 ## Developer And Technical Documents