docs: group Java migration documents

2026-10-26 14:24:01 +00:00 · 2026-09-14 13:10:40 +02:00
1 parent 1de11db82d
commit 00834daccf
@@ -32,28 +32,28 @@ Existing reflective binaries remain supported until consumer release and pack ad

 | Task | API and guide |
 | --- | --- |
-| Define, place, persist, synchronize and remove a custom part | `TMultiPart`, `canPlacePart`, `addPart`, `remPart` — [end-to-end custom-part lifecycle](api/CUSTOM_PARTS.md) |
-| Register block converters | `registerConverter(IPartConverter)` — [registration, state ownership and committed lifecycle](api/BLOCK_CONVERTERS.md) |
-| Register part factories during mod initialization | `registerPartFactory(IPartFactory2, String...)` — [factory timing, payload ownership and migration](api/PART_REGISTRATION.md) |
-| Find the factory registered for a part type | `getPartFactory(String)` — [lookup ownership and Schematica reflection migration](api/FACTORY_LOOKUP.md) |
-| Enumerate microblock materials by numeric ID | `materialCount()`, `materialName(int)`, `getMaterial(int)` — [material enumeration](api/MATERIAL_ENUMERATION.md) |
-| Read a microblock material's block and metadata | `BlockMicroMaterial.block()`, `meta()` — [typed GuideNH query, identity and overrides](api/MATERIAL_ACCESS.md) |
-| Create a microblock with the requested material and side | `MicroblockGenerator.create(MicroblockClass, int, boolean)` — [construction, material traits and GuideNH migration](api/MICROBLOCK_CREATION.md) |
-| Call generated tile capabilities from Java | `TileMultipart`, `IRedstoneTile` and ordinary interfaces — [safe compilation and raw-trait pitfalls](api/TILE_TRAIT_ACCESS.md) |
-| Add aggregate or lifecycle behavior to generated multipart tiles | `registerTrait(marker, trait)` — [custom Java tile traits, stable capabilities and transformer constraints](api/CUSTOM_TILE_TRAITS.md) |
-| Refresh slots after a stored part changes shape | `refreshPartSlots(TMultiPart)` — [ownership, equality and notification responsibilities](api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) |
-| Add material-specific behavior to generated microblocks | `registerTrait(String)` and `IGeneratedMaterial` — [illuminated Java extension, compilation and side contracts](api/MICROBLOCK_EXTENSIONS.md) |
-| Change an existing FMP saw's cutting strength | `ItemSaw.setHarvestLevel(int)` — [state, lifecycle and Iguana migration](api/SAW_STRENGTH.md) |
-| Read/index/search a tile's parts | `jPartList()` — [part collection ownership and order](api/PART_TRAVERSAL.md#collection-ownership-and-ordering) |
-| Run callbacks only on parts still owned by the tile | `forEachPart(Consumer)` — [callback and override behavior](api/PART_TRAVERSAL.md#callback-behavior) |
-| Rebuild parts on an already prepared composite tile | `loadPartList(Collection)` — [part loading](api/PART_LOADING.md) |
-| Select client/server tile capabilities before preparing state and loading | `MultipartGenerator.generateCompositeTile(TileEntity, Iterable, boolean)` — [staged generation and reflection migration](api/COMPOSITE_GENERATION.md) |
-| Assign stored parts during reconstruction, without binding or notifications | `setPartList(List)` — [storage assignment](api/PART_LOADING.md#storage-assignment) |
-| Test a candidate against a selected collection of parts | `testOcclusion(Collection, candidate)` — [occlusion queries and generated hooks](api/OCCLUSION.md) |
-| Test two groups of bounding boxes directly | `NormalOcclusionTest.testBoxes(Iterable, Iterable)` — [box-versus-box queries](api/OCCLUSION.md#box-versus-box-queries) |
-| Read FMP's global render registration ID | `TileMultipart.getRenderID()` — [render-ID meaning, lifecycle and setter](api/RENDER_ID.md) |
-| Inspect an existing tile or converted placeholder with a named result | `getOrConvertTileResult(World, BlockCoord)` — [conversion outcomes and placement lifecycle](api/TILE_CONVERSION.md) |
-| Add or remap multipart button attachment orientations | `ButtonPart.setOrientation(int, ForgeDirection)` — [metadata, face mapping and Et Futurum migration](api/BUTTON_ORIENTATIONS.md) |
+| Define, place, persist, synchronize and remove a custom part | `TMultiPart`, `canPlacePart`, `addPart`, `remPart` - [end-to-end custom-part lifecycle](api/CUSTOM_PARTS.md) |
+| Register block converters | `registerConverter(IPartConverter)` - [registration, state ownership and committed lifecycle](api/BLOCK_CONVERTERS.md) |
+| Register part factories during mod initialization | `registerPartFactory(IPartFactory2, String...)` - [factory timing, payload ownership and migration](api/PART_REGISTRATION.md) |
+| Find the factory registered for a part type | `getPartFactory(String)` - [lookup ownership and Schematica reflection migration](api/FACTORY_LOOKUP.md) |
+| Enumerate microblock materials by numeric ID | `materialCount()`, `materialName(int)`, `getMaterial(int)` - [material enumeration](api/MATERIAL_ENUMERATION.md) |
+| Read a microblock material's block and metadata | `BlockMicroMaterial.block()`, `meta()` - [typed GuideNH query, identity and overrides](api/MATERIAL_ACCESS.md) |
+| Create a microblock with the requested material and side | `MicroblockGenerator.create(MicroblockClass, int, boolean)` - [construction, material traits and GuideNH migration](api/MICROBLOCK_CREATION.md) |
+| Call generated tile capabilities from Java | `TileMultipart`, `IRedstoneTile` and ordinary interfaces - [safe compilation and raw-trait pitfalls](api/TILE_TRAIT_ACCESS.md) |
+| Add aggregate or lifecycle behavior to generated multipart tiles | `registerTrait(marker, trait)` - [custom Java tile traits, stable capabilities and transformer constraints](api/CUSTOM_TILE_TRAITS.md) |
+| Refresh slots after a stored part changes shape | `refreshPartSlots(TMultiPart)` - [ownership, equality and notification responsibilities](api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) |
+| Add material-specific behavior to generated microblocks | `registerTrait(String)` and `IGeneratedMaterial` - [illuminated Java extension, compilation and side contracts](api/MICROBLOCK_EXTENSIONS.md) |
+| Change an existing FMP saw's cutting strength | `ItemSaw.setHarvestLevel(int)` - [state, lifecycle and Iguana migration](api/SAW_STRENGTH.md) |
+| Read/index/search a tile's parts | `jPartList()` - [part collection ownership and order](api/PART_TRAVERSAL.md#collection-ownership-and-ordering) |
+| Run callbacks only on parts still owned by the tile | `forEachPart(Consumer)` - [callback and override behavior](api/PART_TRAVERSAL.md#callback-behavior) |
+| Rebuild parts on an already prepared composite tile | `loadPartList(Collection)` - [part loading](api/PART_LOADING.md) |
+| Select client/server tile capabilities before preparing state and loading | `MultipartGenerator.generateCompositeTile(TileEntity, Iterable, boolean)` - [staged generation and reflection migration](api/COMPOSITE_GENERATION.md) |
+| Assign stored parts during reconstruction, without binding or notifications | `setPartList(List)` - [storage assignment](api/PART_LOADING.md#storage-assignment) |
+| Test a candidate against a selected collection of parts | `testOcclusion(Collection, candidate)` - [occlusion queries and generated hooks](api/OCCLUSION.md) |
+| Test two groups of bounding boxes directly | `NormalOcclusionTest.testBoxes(Iterable, Iterable)` - [box-versus-box queries](api/OCCLUSION.md#box-versus-box-queries) |
+| Read FMP's global render registration ID | `TileMultipart.getRenderID()` - [render-ID meaning, lifecycle and setter](api/RENDER_ID.md) |
+| Inspect an existing tile or converted placeholder with a named result | `getOrConvertTileResult(World, BlockCoord)` - [conversion outcomes and placement lifecycle](api/TILE_CONVERSION.md) |
+| Add or remap multipart button attachment orientations | `ButtonPart.setOrientation(int, ForgeDirection)` - [metadata, face mapping and Et Futurum migration](api/BUTTON_ORIENTATIONS.md) |

 Each guide explains ownership, lifecycle, legacy replacements and limitations, and links to a compiling Java example
 exercised by the test suite. The loading/setter APIs are advanced reconstruction operations; ordinary placement and
@@ -114,7 +114,7 @@ Three advanced methods remain supported because consumers use them directly:

 No reflection is needed to call any of these methods. `operate` and `getOrConvertTile2` retain their documented legacy
 contracts and Java replacements; neither receives an internal-only marker. Removing those bridges still requires
-consumer and internal migration gates. The [consumer audit](../JAVA_MIGRATION_COMPATIBILITY.md#api-boundary-audit)
+consumer and internal migration gates. The [consumer audit](migration/COMPATIBILITY.md#api-boundary-audit)
 records the checked source calls and validation.

 ## Compatibility and remaining work
@@ -141,8 +141,8 @@ Scala dependency requires those gates and removal of FMP's remaining internal Sc

 | Need | Document |
 | --- | --- |
-| What is complete and what comes next? | [Working handoff](../JAVA_MIGRATION_HANDOFF.md), [migration plan](../JAVA_MIGRATION.md) |
-| Which consumers need changes, releases and pack adoption? | [Consumer adoption ledger](../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) |
-| Which binary names, reflective lookups and runtime contracts must survive? | [ABI inventory and consumer audit](../JAVA_MIGRATION_COMPATIBILITY.md) |
-| What has been tested and what still needs a client/pack run? | [Migration history](migration/HISTORY.md), [manual release checks](../JAVA_MIGRATION_MANUAL_CHECKS.md) |
-| Why is some Scala or older Java syntax retained? | [Modern Java policy](../JAVA_MIGRATION.md#modern-java-readability-policy), [compiler/toolchain handoff](../JAVA_MIGRATION.md#modern-java-readability-policy) |
+| What is complete and what comes next? | [Working handoff](migration/HANDOFF.md), [migration plan](migration/README.md) |
+| Which consumers need changes, releases and pack adoption? | [Consumer adoption ledger](migration/COMPATIBILITY.md#java-api-adoption-ledger) |
+| Which binary names, reflective lookups and runtime contracts must survive? | [ABI inventory and consumer audit](migration/COMPATIBILITY.md) |
+| What has been tested and what still needs a client/pack run? | [Migration history](migration/HISTORY.md), [manual release checks](migration/MANUAL_CHECKS.md) |
+| Why is some Scala or older Java syntax retained? | [Modern Java policy](migration/README.md#modern-java-readability-policy), [compiler/toolchain handoff](migration/README.md#modern-java-readability-policy) |
@@ -1,10 +1,10 @@
-# Release notes — the Java port
+# Release notes - the Java port

 ForgeMultipart's implementation moved from Scala to Java. This page is for mod authors who depend on FMP.

 **If you ship a compiled jar and do not rebuild it, nothing here affects you.** Every runtime interface, method
 descriptor and reflective name the audited consumers use was preserved deliberately, and the retained Scala bridges
-still link. The compatibility ledger for what did change is [JAVA_MIGRATION_DIVERGENCES.md](../JAVA_MIGRATION_DIVERGENCES.md).
+still link. The compatibility ledger for what did change is [divergence ledger](migration/DIVERGENCES.md).

 **If you rebuild against the new dev jar, read on.** Recompiling is the case that breaks, and one class of break is
 silent. There are three kinds, in descending order of how badly they fail. The [consumer migration checklist](api/MIGRATION_CHECKLIST.md)
@@ -14,7 +14,7 @@ turns the cases below into concrete compile, runtime, release and pack-adoption

 Six types were Scala traits, which compile to an interface plus a `$class` helper. They are now concrete Java classes
 in the dev jar. Forge's transformer rewrites them back into interfaces at load time, so **existing binaries are
-unaffected** — they already call interface methods, and the runtime type is still an interface.
+unaffected** - they already call interface methods, and the runtime type is still an interface.

 Source compiled against the untransformed dev jar is the problem. `javac` and `scalac` see a class, emit
 `invokevirtual` or `getfield`, and the JVM then rejects it against the runtime interface.
@@ -57,7 +57,7 @@ Confirmed still present on each project's default branch:

 ## 2. Silent behavior changes: recompiled Scala trait composition

-**This is the dangerous one — it compiles cleanly and does the wrong thing at runtime.**
+**This is the dangerous one - it compiles cleanly and does the wrong thing at runtime.**

 A Java interface cannot supply a Scala trait's class supertype or its linearization. When a superclass method and an
 interface default both apply, the superclass wins. So recompiling `extends TMultiPart with TCuboidPart` silently
@@ -132,7 +132,7 @@ still has to be redone against `IRedstoneTile` afterwards. Always target the sta
 raw class the dev jar exposes for a transformed trait.

 Two honest limits on that guarantee. It covers the surface that is documented here and in the
-[compatibility audit](../JAVA_MIGRATION_COMPATIBILITY.md); a dependency in neither can still be caught out, which is
+[compatibility audit](migration/COMPATIBILITY.md); a dependency in neither can still be caught out, which is
 why removal waits on evidence of adoption in released consumer jars rather than on source patches alone. And FMP's own
 source layout will change when Scala goes, since the Java sources currently live under `src/main/scala` for joint
 compilation. That moves no class, package, descriptor or reflective name, so it is invisible to consumers; only
@@ -81,4 +81,4 @@ selection, first acceptance, captured lists, duplicates and exception propagatio
 probes, original-tile ownership, callback order, repeated conversion, initialized example registration, NBT/packet
 state and normal installation. The example compiles as Java 8 without Scala on its compile classpath. FMP still uses
 Scala internally. Physical-client construction/rendering and real consumer inventory/network conversion remain
-[manual integration checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md); the example does not establish consumer adoption.
+[manual integration checks](../migration/MANUAL_CHECKS.md); the example does not establish consumer adoption.
@@ -50,4 +50,4 @@ Et Futurum migration, target-pack adoption and a fresh consumer scan.
 Forge characterization first freezes the old Et Futurum mutation and verifies exact metadata and placement on all six
 faces. API tests verify the two direct calls produce the same arrays, displaced pairs remain one-to-one, invalid input
 is atomic, and the example compiles. A physical client with Et Futurum must still complete the
-[all-face button check](../../JAVA_MIGRATION_MANUAL_CHECKS.md) before release.
+[all-face button check](../migration/MANUAL_CHECKS.md) before release.
@@ -91,4 +91,4 @@ method; the archived run excludes only its obsolete pre-addition inventory asser
 and all archived Forge cases run against the addition, with an independent class/member/body comparison.

 Generating a client tile in the Forge server harness does not prove physical-client microblock creation or GPU output.
-Schematica and GuideNH preview rendering remain [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+Schematica and GuideNH preview rendering remain [manual release checks](../migration/MANUAL_CHECKS.md).
@@ -76,6 +76,6 @@ reflection, server construction, NBT loading, unbound ownership and the Java exa
 Scala excluded from its classpath. Archived callers and the private field's binary shape are checked separately.

 Physical-client microblock construction and Schematica preview rendering remain
-[manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md). A dedicated Forge server strips `clientTrait()`, so
+[manual release checks](../migration/MANUAL_CHECKS.md). A dedicated Forge server strips `clientTrait()`, so
 calling client microblock creation there fails before it can exercise a real client preview; the server fixture does
 not claim that coverage.
@@ -62,7 +62,7 @@ Extra Utilities' NEI handlers use both tuple fields; both indexed replacements a

 The static and companion `getIdMap()` methods are deprecated, with their original descriptors and live-array
 behavior retained. This change does not authorize removal of either method. The
-[consumer adoption ledger](../../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) records the migrations and
+[consumer adoption ledger](../migration/COMPATIBILITY.md#java-api-adoption-ledger) records the migrations and
 released pack versions still needed.

 ## Validation
@@ -89,4 +89,4 @@ Server Forge tests cover both exact reflective entries, factory/material identit
 ownership, material trait injection, callback failures and scratch reuse. The Java example tests all 256 shape-byte
 values without copying bindings or altering the source and compiles without Scala. Archived callers, existing APIs,
 method bodies and generated dumps are checked separately. Physical-client creation and GuideNH preview/GPU output
-remain [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md); reference checkouts and adoption status are unchanged.
+remain [manual release checks](../migration/MANUAL_CHECKS.md); reference checkouts and adoption status are unchanged.
@@ -47,7 +47,7 @@ The existing transformer cannot safely handle all inherited field/method accesse
 therefore delegate to an ordinary helper using an **Object parameter**, then cast to `Microblock` in that helper.
 This forces the required runtime cast and keeps loops, allocation and callbacks outside the transformed input.
 The three example files compile with Scala excluded from the Java classpath; they use Java 8 syntax because that is
-the verified joint-compilation/test boundary. See the [compiler constraints](../../JAVA_MIGRATION_HANDOFF.md#retained-compiler-constraints).
+the verified joint-compilation/test boundary. See the [compiler constraints](../migration/HANDOFF.md#retained-compiler-constraints).

 ## Behavioral contract

@@ -82,7 +82,7 @@ A headless compiler probe retains the actual compiled client method in a uniquel
 side annotation from the test input. It checks generated dispatch, pass filtering and queued coordinates/colour/bounds.
 That is **not** a physical-client construction, side-selection or GPU test. Existing side-filtering tests cover the
 compiler separately; actual client generation, connector-dependent halos, lighting and previews remain required
-checks in the [manual checklist](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+checks in the [manual checklist](../migration/MANUAL_CHECKS.md).

 ProjectRed's reference checkout is unchanged. Its migration must preserve registration order/names, wire the existing
 configuration and halo queue, release the consumer, and validate the released jar in the pack. Keep ProjectRed's
@@ -124,7 +124,7 @@ JVM tests cover both directions, early rejection, original exceptions, null boun
 subtype/non-list collections, override routing and the shape example. A Forge test demonstrates that the generated
 partial trait rejects overlapping partial parts that plain pair tests accept. Existing descriptors, generated output,
 and frozen pre-change callers are checked separately. Actual client previews and full-pack adoption remain covered
-by the [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+by the [manual release checks](../migration/MANUAL_CHECKS.md).

 Box-query tests run the same snapshot, input-failure, ordering, null and exception contracts against both legacy entries
 and the Java entry. The compiling example also covers touching tolerance and containment; frozen pre-change tests
@@ -98,5 +98,5 @@ callback input mutation and partial-failure behavior. Forge tests cover slot-cac
 plus Java assignment/loading on a generated client tile and explicit render-cache rebuilding. The latter does not run
 a real client world or GPU rendering; GuideNH/Schematica previews and full-pack adoption remain manual release gates.

-The [consumer ledger](../../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) records the inspected source
+The [consumer ledger](../migration/COMPATIBILITY.md#java-api-adoption-ledger) records the inspected source
 revisions and pending consumer changes/releases. The supplied reference checkouts are unchanged.
@@ -88,4 +88,4 @@ payload objects/cursors. The new entry runs through the same checks, and the exa
 The archived pre-change Forge test mod and JVM fixtures run against the new implementation without recompiling their
 callers. Existing member descriptors, method bodies, Scala signatures and generated output are checked separately.
 The dedicated-server suite invokes the client construction method with a real packet; physical-client rendering and
-full-pack adoption remain [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+full-pack adoption remain [manual release checks](../migration/MANUAL_CHECKS.md).
@@ -98,7 +98,7 @@ GuideNH also reflects `partList`, `partList_$eq` and `loadParts` while reconstru
 uses to the Java getter does not migrate its setter/loading contracts. Their [Java replacements](PART_LOADING.md)
 are implemented; the consumer patch, release and pack adoption remain separate work. No reference checkout was edited.

-The [adoption ledger](../../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) records inspected revisions and
+The [adoption ledger](../migration/COMPATIBILITY.md#java-api-adoption-ledger) records inspected revisions and
 the remaining release gates. JVM checks cover both getter forms, mutable storage, callback mutation/reentrancy,
 detached/rebound parts, override dispatch and failures. The Forge test removes and adds real parts during traversal
 of a generated slotted tile. Client rendering and full-pack adoption remain manual release checks.
@@ -37,4 +37,4 @@ supplied consumer sources or the frozen downstream member inventory; consumer ch
 JVM tests cover the initial sentinel, both legacy setters, Java accessors, signed integer boundaries and multiple
 block instances reading the global value. Forge verifies the server sentinel and shared block state without loading
 the client renderer. Frozen callers, class APIs and generated output are checked separately. Actual client allocation,
-handler registration and GPU rendering remain [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+handler registration and GPU rendering remain [manual release checks](../migration/MANUAL_CHECKS.md).
@@ -62,4 +62,4 @@ tile-only method and need no rename for this contract. Consumer checkouts remain
 Forge tests run the same scenarios through both legacy entries and the Java entry: existing tile identity, air,
 nonconvertible solid blocks, unrelated tile entities, bound torch placeholders, repeated conversions and subsequent
 normal placement. Archived callers, class/member APIs and generated outputs are checked separately. Actual client
-preview rendering remains a [manual release check](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+preview rendering remains a [manual release check](../migration/MANUAL_CHECKS.md).
@@ -9,8 +9,8 @@ questions.
  have linked?" It covers all 27 ForgeMultipart consumers in the supplied GTNH daily `2026-08-25+700` instance, plus
  UtilitiesInExcess as the planned Extra Utilities replacement.

-Intentional differences from the reference belong in the [divergence ledger](JAVA_MIGRATION_DIVERGENCES.md), and the
-consumer-facing summary of what breaks on rebuild is in the [release notes](docs/RELEASE_NOTES.md).
+Intentional differences from the reference belong in the [divergence ledger](DIVERGENCES.md), and the
+consumer-facing summary of what breaks on rebuild is in the [release notes](../RELEASE_NOTES.md).

 # Part 1 - Downstream ABI inventory

@@ -115,7 +115,7 @@ Everything in this section must keep its exact descriptor, or a named consumer f
 | `TEdgePart$class` | `$init$` | OpenComputers |

 The `JPartialOcclusion$class` bridge already added on this branch follows the right pattern, but note that
-`JPartialOcclusion$class` itself has **no** downstream caller in the pack — the two consumers that touch
+`JPartialOcclusion$class` itself has **no** downstream caller in the pack - the two consumers that touch
 `JPartialOcclusion` (ForgeRelocationFMP, WitchingGadgets) only call `getPartialOcclusionBoxes()Ljava/lang/Iterable;`.
 The eight helpers above are the ones that actually matter.

@@ -145,12 +145,12 @@ so the Java-first collection API mostly exists already and the Scala overloads a
 The branch now supplies `NormalOcclusionTest.testBoxes(java.lang.Iterable, java.lang.Iterable)` for the box-list
 contract. Both old `apply(Traversable, Traversable)` entries remain, with deprecations pointing to the Java entry.
 The shipping ForgeRelocationFMP/OpenComputers companion calls still require their exact descriptor until adoption;
-see the [migration guide](docs/api/OCCLUSION.md#box-versus-box-queries) and consumer ledger.
+see the [migration guide](../api/OCCLUSION.md#box-versus-box-queries) and consumer ledger.

 `MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` now provides the Java registration entry without
 Scala overload resolution. Both `registerParts(IPartFactory2, Seq)` entries are deprecated; all eight existing
 registration descriptors remain. ProjectRed's sequence and ForgeRelocationFMP's function companion calls still need
-their bridges until release/adoption. See the [registration guide](docs/api/PART_REGISTRATION.md).
+their bridges until release/adoption. See the [registration guide](../api/PART_REGISTRATION.md).

 `IDWriter`, ported on this branch, has **zero** downstream references. Its four deprecated Scala function accessors
 are not load-bearing and can be dropped.
@@ -159,30 +159,30 @@ are not load-bearing and can be dropped.

 These fail at runtime, not at link time, so ABI tooling will not catch a break. 20 string constants across:

- `guidenh-1.3.20` — the broadest reflective consumer: `MultipartGenerator`/`MultipartGenerator$`,
+- `guidenh-1.3.20` - the broadest reflective consumer: `MultipartGenerator`/`MultipartGenerator$`,
  `MultipartHelper`/`MultipartHelper$`, `MultipartRenderer`/`MultipartRenderer$`, `TileMultipart`,
  `TileMultipartClient`, `MicroblockClient`, `Microblock`, `MicroblockClass`, `MicroblockGenerator$`,
  `BlockMicroMaterial`/`BlockMicroMaterial$`, `MicroMaterialRegistry`/`MicroMaterialRegistry$`, `BlockMultipart`.
- `Schematica-1.12.6-GTNH` — `TileMultipart`, `TMultiPart`, `MultiPartRegistry$`, `MultipartGenerator$`, `MicroblockClass`.
- `Galacticraft-3.4.33-GTNH` — `TileMultipart`, `MicroMaterialRegistry`, `BlockMicroMaterial`.
- `Waila-1.19.31` — `BlockMultipart`.
- `AE2`, `ae2fc` — `TileMultipart`.
- `etfuturum-2.6.52-GTNH` — `codechicken.multipart.minecraft.ButtonPart`.
+- `Schematica-1.12.6-GTNH` - `TileMultipart`, `TMultiPart`, `MultiPartRegistry$`, `MultipartGenerator$`, `MicroblockClass`.
+- `Galacticraft-3.4.33-GTNH` - `TileMultipart`, `MicroMaterialRegistry`, `BlockMicroMaterial`.
+- `Waila-1.19.31` - `BlockMultipart`.
+- `AE2`, `ae2fc` - `TileMultipart`.
+- `etfuturum-2.6.52-GTNH` - `codechicken.multipart.minecraft.ButtonPart`.

 Note that both the class and its `$` companion are named in several cases, so renaming or removing a companion
 object breaks these even where no bytecode reference exists.

 The branch now offers `MultiPartRegistry.getPartFactory(String): IPartFactory2` to replace Schematica's private
-registry-map reflection, with a [migration guide](docs/api/FACTORY_LOOKUP.md). Its old companion field retains the
+registry-map reflection, with a [migration guide](../api/FACTORY_LOOKUP.md). Its old companion field retains the
 exact private Scala mutable-map shape and live backing; the public addition does not authorize removing that field
 before consumer release/adoption. Generator reflection and preview lifecycle remain separate contracts.

 `ButtonPart.setOrientation(int, ForgeDirection): void` now replaces Et Futurum's four reflective array writes and
-keeps the two direction maps consistent; [guide](docs/api/BUTTON_ORIENTATIONS.md). The existing public mutable static
+keeps the two direction maps consistent; [guide](../api/BUTTON_ORIENTATIONS.md). The existing public mutable static
 `metaSideMap` and `sideMetaMap` fields retain their exact names, types and modifiers for old releases. Removing or
 narrowing them still waits for a migrated Et Futurum release, target-pack adoption and a fresh reflective-source scan.

-`ItemSaw.setHarvestLevel(int): void` now replaces Iguana's private-field write; [guide](docs/api/SAW_STRENGTH.md).
+`ItemSaw.setHarvestLevel(int): void` now replaces Iguana's private-field write; [guide](../api/SAW_STRENGTH.md).
 The existing private `harvestLevel: int` field remains for old releases and shares storage with the setter. It loses
 only `ACC_FINAL`, which makes the supported mutation explicit and keeps reflective writes working. Removal still
 waits for an Iguana release, target-pack adoption and a fresh scan.
@@ -233,7 +233,7 @@ Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMult
   The branch now adds `MultipartGenerator.generateCompositeTile(TileEntity, java.lang.Iterable, boolean)` while
   retaining the exact companion Scala descriptor/body. GuideNH's old Scala sequence is not assignable to the new
   Java parameter, so its existing matcher still falls back to the companion. Both old and new reflective contracts
-   are tested; migration requires a Java parts collection. See the [guide](docs/api/COMPOSITE_GENERATION.md).
+   are tested; migration requires a Java parts collection. See the [guide](../api/COMPOSITE_GENERATION.md).

 2. **`MicroblockGenerator$.create` is matched by exact parameter types**, including `pts[0].getName()` string-compared
   against `"codechicken.microblock.MicroblockClass"`. That pins `create(MicroblockClass, int, boolean)` on the
@@ -241,7 +241,7 @@ Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMult
   lookup even though every call site still links.

   The existing static `MicroblockGenerator.create(MicroblockClass, int, boolean)` now has a
-   [guide and compiling example](docs/api/MICROBLOCK_CREATION.md). Both exact reflective entries are tested; no API
+   [guide and compiling example](../api/MICROBLOCK_CREATION.md). Both exact reflective entries are tested; no API
   shape or production method body changes were needed. GuideNH must change its explicitly selected owner and receiver
   before it stops using the companion. Release/adoption, shape-setter override checks and client previews remain gates.

@@ -249,14 +249,14 @@ Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMult
   `setPartList(java.util.List)` and `loadPartList(java.util.Collection)`, while retaining the exact legacy setter and
   loader descriptors and override dispatch. Dropping the old setter in favor of the Java method would still break
   guidenh invisibly. Exact and assignability-based reflective tests cover both legacy contracts. `resolvePartList` also falls back to a public *field*
-   named `partList`, which never existed — Scala emits the field private — so that path is dead in the reference too.
+   named `partList`, which never existed - Scala emits the field private - so that path is dead in the reference too.

 `MultipartHelper$` is retained on the strength of the fallback path alone: the static is found first today, so the
 companion is never reached in practice. That is a weaker justification than the two "companion only" entries above,
 but the cost of keeping a four-method forwarder is negligible against a silent break.

 GuideNH's private `BlockMicroMaterial.block: Block` and `meta: int` fields remain unchanged for its accessor mixin.
-Existing public virtual `block()` / `meta()` now have a [typed query guide](docs/api/MATERIAL_ACCESS.md) and regression
+Existing public virtual `block()` / `meta()` now have a [typed query guide](../api/MATERIAL_ACCESS.md) and regression
 coverage; no descriptor or method body changed. The mixin reads constructor fields whereas direct calls honor
 subclass overrides, as the old reflective fallback already did. Remove the consumer's mixin only when adopting the
 typed query; FMP field removal still waits for released-consumer adoption.
@@ -367,7 +367,7 @@ present. Only the plugin is one of the 27 FMP consumers.

 ## Consumer findings

-### ProjectRed — deepest current consumer
+### ProjectRed - deepest current consumer

 ProjectRed is not merely an optional integration. Wires, framed wires, bundled wires, gates, lamps, buttons, pipes,
 solar panels, and fabricated gates are FMP parts. Its 141 touching classes dominate the installed binary surface.
@@ -400,7 +400,7 @@ trait linearization, tile and microblock code generation, redstone tile traits,
 and the micro-material system. A launch-only smoke test is inadequate; illuminated microblocks, gates, face/framed
 wires, and routed pipes need functional fixtures.

-### Extra Utilities 1.2.12 — active supported consumer
+### Extra Utilities 1.2.12 - active supported consumer

 Extra Utilities remains in the supported compatibility target. UtilitiesInExcess is its intended replacement;
 approval to switch that target and adoption of the replacement in the pack are still pending. Preserve the current
@@ -430,7 +430,7 @@ names and descriptors. Obfuscated Minecraft method names should not be treated a
 that Java wrappers still compose into the same generated tile. UtilitiesInExcess does not make this compatibility
 burden disappear until existing worlds and the old mod have been retired.

-### OpenComputers — generated slot state is part of the effective API
+### OpenComputers - generated slot state is part of the effective API

 OpenComputers converts its cable and 3D print blocks to parts and registers `oc` cable/print factories.

@@ -450,7 +450,7 @@ OpenComputers converts its cable and 3D print blocks to parts and registers `oc`
 including its public generated state. Test a print whose on/off shapes occupy different slots next to a cable and a
 face part.

-### ProjectBlue — Java parts built on Scala shim bases
+### ProjectBlue - Java parts built on Scala shim bases

 ProjectBlue defines tiny Scala bridge bases (`JFacePart`, `JCuboidFacePart`, `JCenterPart`) so most of its FMP code
 can be Java. Its active multipart is the bundled-redstone control panel.
@@ -624,10 +624,10 @@ The branch now provides `MultiPartRegistry.getPartFactory(String)` as the suppor
 It returns the exact registered factory or null without construction or missing-name logging. Schematica can reflect
 this public static method and continue invoking `MicroblockClass.create(client, materialId)` on the returned object;
 `loadPart` would incorrectly choose the server factory path for its client preview. The old private field remains.
-See the [guide](docs/api/FACTORY_LOOKUP.md) and the now-available [Java tile generator](docs/api/COMPOSITE_GENERATION.md);
+See the [guide](../api/FACTORY_LOOKUP.md) and the now-available [Java tile generator](../api/COMPOSITE_GENERATION.md);
 consumer patches and pack adoption remain pending.

-### UtilitiesInExcess — future replacement, already a substantial consumer
+### UtilitiesInExcess - future replacement, already a substantial consumer

 UtilitiesInExcess is not in the `+700` JAR scan but is in scope because it is intended to replace Extra Utilities.

@@ -767,14 +767,14 @@ behavior:
 This ledger tracks migration of a specific legacy contract, not completion of an entire consumer's migration.
 Factory registration/lookup, material enumeration, tile collection/traversal access, tile loading/storage assignment,
 tile occlusion and box queries, render-ID accessors and named tile conversion results are implemented on
-`algent/java`. The [API index](docs/API.md) links the guides and compiling Java examples. These additions are not yet
+`algent/java`. The [API index](../API.md) links the guides and compiling Java examples. These additions are not yet
 tied to a released minimum dependency version. Unlisted contracts remain governed by the inventories above.

 | Legacy contract | Consumer and inspected source | Supported replacement | Consumer migration/release | Target-pack adoption and removal gate |
 | --- | --- | --- | --- | --- |
-| `TRedstoneTile.openConnections(int)` | ProjectRed `e173952e96a4`: `transmission/redwires.scala` | Existing stable `IRedstoneTile.openConnections(int)` with the same mask/rotation logic; [guide](docs/api/TILE_TRAIT_ACCESS.md) | FMP source-access example and Forge coverage complete; consumer source patch/release pending | Retain the old runtime interface descriptor until adoption |
-| `TSlottedTile.v_partMap()` array mutation | OpenComputers `2c00f79be24b`: `PrintPart.toggleState` | `TileMultipart.refreshPartSlots(part)`; [equality, cache and notification contract](docs/api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) | FMP API/example complete; consumer source patch/release pending, preserving validation and following sound/notify/packet/schedule order | Keep the live array/accessor ABI until released pack adoption; do not replace it with reflection or a whole-tile reload |
-| External Scala `LightMicroblock` registered through `MicroblockGenerator.registerTrait` | ProjectRed `e173952e96a4`: `illumination/lightmicroblocks.scala` | Java source trait registered by name, `IGeneratedMaterial`, typed sibling traversal and halo helper; [example](docs/api/MICROBLOCK_EXTENSIONS.md) | FMP example tested; consumer rewrite/release, existing config/halo wiring and physical-client checks pending | Retain external Scala trait ingestion until released-consumer adoption and internal Scala-trait removal |
+| `TRedstoneTile.openConnections(int)` | ProjectRed `e173952e96a4`: `transmission/redwires.scala` | Existing stable `IRedstoneTile.openConnections(int)` with the same mask/rotation logic; [guide](../api/TILE_TRAIT_ACCESS.md) | FMP source-access example and Forge coverage complete; consumer source patch/release pending | Retain the old runtime interface descriptor until adoption |
+| `TSlottedTile.v_partMap()` array mutation | OpenComputers `2c00f79be24b`: `PrintPart.toggleState` | `TileMultipart.refreshPartSlots(part)`; [equality, cache and notification contract](../api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) | FMP API/example complete; consumer source patch/release pending, preserving validation and following sound/notify/packet/schedule order | Keep the live array/accessor ABI until released pack adoption; do not replace it with reflection or a whole-tile reload |
+| External Scala `LightMicroblock` registered through `MicroblockGenerator.registerTrait` | ProjectRed `e173952e96a4`: `illumination/lightmicroblocks.scala` | Java source trait registered by name, `IGeneratedMaterial`, typed sibling traversal and halo helper; [example](../api/MICROBLOCK_EXTENSIONS.md) | FMP example tested; consumer rewrite/release, existing config/halo wiring and physical-client checks pending | Retain external Scala trait ingestion until released-consumer adoption and internal Scala-trait removal |
 | `MultiPartRegistry$.registerParts(IPartFactory2, Seq)` and existing array calls | ProjectRed `e173952e96a4`: transmission, expansion and fabrication proxies | `MultiPartRegistry.registerPartFactory` with existing `IPartFactory2` methods and unchanged IDs | Source patch and release pending; Boolean-factory proxies separately need the two-method adapter described in the guide | No migrated pack version verified; retain all registration bridges and external trait support |
 | `MultiPartRegistry$.registerParts(Function2, Seq)` | ForgeRelocationFMP `49a810b8c63b`: proxy init registering `rfmp_frame` | `IPartFactory2` creating a fresh `FramePart` on both paths, registered through `registerPartFactory` | Source patch and release pending; preserve `rfmp_frame` and keep converter/pass-through registration | No migrated pack version verified; retain the function companion descriptor |
 | `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | UtilitiesInExcess `3e107a1fe9bc15fcb6a808242ffda1354dac7c3a`: `FMPRecipeLoader.run`, `UEMultipartItem.getSubItems` | `materialCount()` with `materialName(int)` and, when needed, `getMaterial(int)` | Source patch and first released version pending; checkout used as reference only | No migrated pack version verified; retain the bridge |
@@ -788,9 +788,9 @@ tied to a released minimum dependency version. Unlisted contracts remain governe
 | Private `MultiPartRegistry$` Scala `typeMap` field and `Map.get` / `Option` | Schematica `3b03ee937953`: `nbt.ForgeMultipart.init` and `createPart` | Call public static `MultiPartRegistry.getPartFactory(partID)` directly; keep material lookup, `MicroblockClass.create(client, materialId)` and whole-preview rejection | Source patch/release pending; lookup and Java tile generation implemented | No migrated pack version verified; retain the exact private live Scala-map field |
 | `MultipartGenerator$.generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` | Schematica `3b03ee937953` exact reflection; GuideNH `7d8fb44e77b9` static-first assignability matcher | Static `MultipartGenerator.generateCompositeTile(TileEntity, java.lang.Iterable, boolean)` with Java parts; retain subsequent state setup/loading | Source patches/releases pending; preserve client part construction, candidate-reuse branch and notification order | No migrated pack version verified; retain the companion and Scala descriptor |
 | `MicroblockGenerator$.create(MicroblockClass, int, boolean)` exact reflection and private shape copy | GuideNH `7d8fb44e77b9`: `getMicroblockGeneratorCreate`, `promoteMicroblockToClient` | Existing static `MicroblockGenerator.create` with the same parameter types/order; recreate family/material and restore encoded shape through public API | Source patch/release pending; guide/example tested on server, physical client and custom shape-setter overrides require adoption checks | No migrated pack version verified; retain companion singleton and exact descriptor |
-| Private `BlockMicroMaterial.block` / `meta` accessor mixin and reflective material query | GuideNH `7d8fb44e77b9`: `AccessorBlockMicroMaterial`, `resolvePrimaryMicroblockId` | Direct `jPartList()`, `Microblock.material()`, `getMaterial(int)`, `BlockMicroMaterial.block()` / `meta()`; [typed example](docs/api/MATERIAL_ACCESS.md) | Source patch/release pending; remove mixin, retain export filtering/failure policy, validate getter overrides and optional loading | No migrated pack version verified; retain private fields |
-| Reflective mutation of `ButtonPart.metaSideMap` / `sideMetaMap` | Et Futurum Requiem `78a5744dfd33`: `compat.CompatMisc.runModHooksInit` | Two direct `ButtonPart.setOrientation(int, ForgeDirection)` calls; [mapping and lifecycle guide](docs/api/BUTTON_ORIENTATIONS.md) | FMP API/example complete; consumer source patch and first released version pending | Retain both public mutable arrays until the migrated release is in the target pack and a fresh scan confirms no legacy access |
-| Reflective mutation of private `ItemSaw.harvestLevel` | IguanaTweaksTConstruct `2bc09889d3e2`: `modcompat.fmp.IguanaFMPCompat.postInit` | Read `harvestLevel()` and call `setHarvestLevel(int)`; [state and lifecycle guide](docs/api/SAW_STRENGTH.md) | FMP API/example complete; consumer source/lifecycle patch and first released version pending | Retain the private field until the migrated release is in the target pack; ensure Iguana runs before ForgeMicroblock post-init and rescan for legacy access |
+| Private `BlockMicroMaterial.block` / `meta` accessor mixin and reflective material query | GuideNH `7d8fb44e77b9`: `AccessorBlockMicroMaterial`, `resolvePrimaryMicroblockId` | Direct `jPartList()`, `Microblock.material()`, `getMaterial(int)`, `BlockMicroMaterial.block()` / `meta()`; [typed example](../api/MATERIAL_ACCESS.md) | Source patch/release pending; remove mixin, retain export filtering/failure policy, validate getter overrides and optional loading | No migrated pack version verified; retain private fields |
+| Reflective mutation of `ButtonPart.metaSideMap` / `sideMetaMap` | Et Futurum Requiem `78a5744dfd33`: `compat.CompatMisc.runModHooksInit` | Two direct `ButtonPart.setOrientation(int, ForgeDirection)` calls; [mapping and lifecycle guide](../api/BUTTON_ORIENTATIONS.md) | FMP API/example complete; consumer source patch and first released version pending | Retain both public mutable arrays until the migrated release is in the target pack and a fresh scan confirms no legacy access |
+| Reflective mutation of private `ItemSaw.harvestLevel` | IguanaTweaksTConstruct `2bc09889d3e2`: `modcompat.fmp.IguanaFMPCompat.postInit` | Read `harvestLevel()` and call `setHarvestLevel(int)`; [state and lifecycle guide](../api/SAW_STRENGTH.md) | FMP API/example complete; consumer source/lifecycle patch and first released version pending | Retain the private field until the migrated release is in the target pack; ensure Iguana runs before ForgeMicroblock post-init and rescan for legacy access |
 | `NormalOcclusionTest$.apply(Traversable, Traversable)` | OpenComputers `2c00f79be24b`: `common.block.Cable.canConnectFromSideFMP`, `server.network.Network.canConnectFromSideFMP` | `NormalOcclusionTest.testBoxes(ownBounds.asJava, otherBounds)`; `otherBounds` already comes from Java `getOcclusionBoxes()` | Source patch and release pending; retain side/color/face filtering | No migrated pack version verified; retain the companion and descriptor |
 | `NormalOcclusionTest$.apply(Traversable, Traversable)` | ForgeRelocationFMP `49a810b8c63b`: `FramePart.occlusionTest` | `NormalOcclusionTest.testBoxes(boxes.asJava, getOcclusionBoxes)`; retain combined normal/partial/collision boxes and caller order | Source patch and release pending; preserve temporary face bounds and replacement protocol | No migrated pack version verified; retain the companion and descriptor |

@@ -839,7 +839,7 @@ server slot rebuilding/notifications and client storage/loading/render-cache que
 consumer release and pack adoption are still separate gates.

 Tile collection occlusion is implemented as `testOcclusion(Collection<? extends TMultiPart>, TMultiPart)`, documented
-in the [occlusion guide](docs/api/OCCLUSION.md). The supplied Java/Scala source search found no direct consumer calls or
+in the [occlusion guide](../api/OCCLUSION.md). The supplied Java/Scala source search found no direct consumer calls or
 overrides of the old two-argument tile `occlusionTest` and no `testOcclusion` name collisions. The frozen ABI floor
 likewise contains no direct reference to that tile descriptor. The legacy hook is nevertheless required by generated
 `TPartialOcclusionTile` behavior and by existing tile placement/replacement dispatch; it remains supported.
@@ -856,10 +856,10 @@ calls, touching tolerance and original input/callback exceptions. Both legacy en
 their descriptors or bodies. The Java example compiles with Scala excluded; the shared private copy helper only widens
 its generic input to accept box subclasses. The source check found the three box-list calls listed above and no
 `testBoxes` collision. The installed `+719` rescan retains all 386 member/type/reflection rows from `+678` across 27
-consumers. Evidence: `run/migration-box-occlusion-reference/`; [guide](docs/api/OCCLUSION.md#box-versus-box-queries).
+consumers. Evidence: `run/migration-box-occlusion-reference/`; [guide](../api/OCCLUSION.md#box-versus-box-queries).

 Factory registration is implemented as `registerPartFactory(IPartFactory2, String...)`, with a
-[guide and compiling example](docs/api/PART_REGISTRATION.md). A probe against the old Java overload family required
+[guide and compiling example](../api/PART_REGISTRATION.md). A probe against the old Java overload family required
 Scala `Seq`/`Function2` even for Java arrays and factories; the new name compiles without Scala. All eight legacy
 static/companion entries retain their bodies/descriptors. Both `IPartFactory2` sequence entries are deprecated, and
 the older Boolean/function adapter deprecations now identify the supported replacement.
@@ -872,7 +872,7 @@ across 27 consumers. Schematica's private registry-map dependency is separate an
 checkouts remain unchanged. Evidence: `run/migration-registration-reference/`.

 Render-ID access is implemented as `TileMultipart.getRenderID()` / `setRenderID(int)`, with a
-[lifecycle guide](docs/api/RENDER_ID.md). No direct use of the four old static/companion accessors or new-name collision
+[lifecycle guide](../api/RENDER_ID.md). No direct use of the four old static/companion accessors or new-name collision
 was found in FMP-related consumer source, and the frozen member inventory contains none of those descriptors.
 Internal block/renderer calls retain the old paths and share the same global value; all four legacy entries remain
 with deprecations. This addition does not replace GuideNH's renderer reflection or allocate/register a renderer.
@@ -880,7 +880,7 @@ JVM and dedicated-server checks preserve the -1 sentinel, unrestricted integer a
 physical-client rendering remains a separate gate. Evidence: `run/migration-render-id-reference/`.

 Tile conversion is available as `TileMultipart.getOrConvertTileResult(World, BlockCoord)`, returning an immutable
-`TileConversionResult` with `getTile()` / `isConverted()`; see the [guide](docs/api/TILE_CONVERSION.md). Both legacy
+`TileConversionResult` with `getTile()` / `isConverted()`; see the [guide](../api/TILE_CONVERSION.md). Both legacy
 static/companion tuple methods remain with deprecations and unchanged bodies/descriptors. The new API wraps their
 existing path, retaining existing-tile identity, converter dispatch and uninstalled-placeholder behavior.

@@ -912,7 +912,7 @@ Forge tests; the full current suite and independent ABI comparison check the int
 generation/worldless loading is covered, while physical-client microblock construction and GPU previews remain manual.
 Reference checkouts and consumer adoption remain unchanged. Evidence: `run/migration-composite-generation-reference/`.

-GuideNH's microblock creation contract is documented at [microblock creation](docs/api/MICROBLOCK_CREATION.md). The
+GuideNH's microblock creation contract is documented at [microblock creation](../api/MICROBLOCK_CREATION.md). The
 static Java method already existed, so this slice adds Javadocs, tests and an example with no production API/body
 changes. GuideNH hardcodes the companion owner and caches its singleton; its source must switch both to use the static
 method. It copies only shape after recreation, not arbitrary custom state or binding. The Java example preserves
@@ -929,7 +929,7 @@ from the unchanged archived Forge mod pass. Physical-client creation/GPU preview
 server strips the client's factory method. All 386 pack ABI/reflection rows remain across 27 consumers, and reference
 checkouts are unchanged. Evidence: `run/migration-microblock-creation-reference/`.

-GuideNH's block/meta query now has a [typed example and contract](docs/api/MATERIAL_ACCESS.md) using existing public
+GuideNH's block/meta query now has a [typed example and contract](../api/MATERIAL_ACCESS.md) using existing public
 methods throughout. The baseline pins constructor identity/raw metadata and the distinction between virtual getters
 and raw mixin fields. Forge exercises first-usable-part ordering, non-block/invalid-block filtering, registry aliases,
 metadata formatting and failure propagation. Getter overrides are intentional public semantics; the old mixin bypasses
@@ -942,7 +942,7 @@ Evidence: `run/migration-material-access-reference/`; archived validation retain

 Rechecked 2026-09-05 across 28 source checkouts and active Extra Utilities compatibility. Searches cover method
 names, FMP-importing Java/Scala source, reflective names and the installed `+719` constant-pool inventory. No external
-calls were found to the 15 tile/material-registry hooks listed in [Phase 9.2](JAVA_MIGRATION.md#92--mark-the-internal-boundary).
+calls were found to the 15 tile/material-registry hooks listed in [Phase 9.2](README.md#92--mark-the-internal-boundary).
 The registry's five companion forwarders carry matching Javadocs. Common-name matches included GuideNH comments
 explicitly avoiding `from` / `copyFrom` and WR-CBE's unrelated `RenderWireless.loadIcons`; neither calls these hooks.
 This is an audit of the supplied references, not proof about every possible external mod or dynamic lookup.
@@ -950,7 +950,7 @@ This is an audit of the supplied references, not proof about every possible exte
 The supported exceptions are actual calls: OpenComputers `2c00f79be24b`, `PrintPart.scala:171`, clears the old slot
 entries before `tile.bindPart(this)`; ProjectRed `e173952e96a4`, `gatepartrs.scala:74`, calls
 `tile.internalPartChange(this)` between its own packet/dirty work and selective external-neighbor notification.
-The [API guide](docs/API.md#supported-api-and-internal-hooks) preserves both contracts. The old `bindPart` comment's
+The [API guide](../API.md#supported-api-and-internal-hooks) preserves both contracts. The old `bindPart` comment's
 blanket prohibition on external calls was incorrect. Cache binding does not place/rebind a part, and it is not a
 universal idempotent refresh; local part notification does not implicitly perform world updates.

@@ -963,7 +963,7 @@ Evidence: `run/migration-api-boundary-reference/`, including source revisions an

 ## Java illuminated microblock extension

-The ProjectRed-style [Java example](docs/api/MICROBLOCK_EXTENSIONS.md) uses public name-based registration and
+The ProjectRed-style [Java example](../api/MICROBLOCK_EXTENSIONS.md) uses public name-based registration and
 `IGeneratedMaterial`; no consumer reflection or Scala classpath is needed. Register the input before class loading,
 keep inherited access in an ordinary helper with Object parameters, and dispatch via the stable Microblock base.
 The example preserves metadata 16–31, cutter metadata modulo 16, all-shape trait selection, strict sibling selection,
@@ -1016,7 +1016,7 @@ changes, while each externally observed behavior has a named consumer and a focu

 ## Java block converter guidance

-The existing `IPartConverter` and static `registerConverter` now have a [Java guide and compiling example](docs/api/BLOCK_CONVERTERS.md).
+The existing `IPartConverter` and static `registerConverter` now have a [Java guide and compiling example](../api/BLOCK_CONVERTERS.md).
 No production descriptor or method body changed. Reference calls confirm Chisel's block/metadata selection,
 ForgeRelocationFMP's frame construction, OpenComputers' original cable/print tile lookup and AE2's cable-bus state copy.
 Their converter registrations need no replacement API; companion users can select the existing static entry.
@@ -1031,7 +1031,7 @@ require integration validation. This is FMP API coverage, not a released consume

 ## Stable Java access to transformed tile traits

-The [tile access guide](docs/api/TILE_TRAIT_ACCESS.md) distinguishes raw dev-jar classes from runtime interfaces.
+The [tile access guide](../api/TILE_TRAIT_ACCESS.md) distinguishes raw dev-jar classes from runtime interfaces.
 Actual javac callers reproduce `IncompatibleClassChangeError` for `TRedstoneTile.openConnections` and `NoSuchFieldError`
 for `TSlottedTile.v_partMap`; the same generated tiles work through `IRedstoneTile` and `TileMultipart.partMap`.
 `IRedstoneTile` is now documented as a supported capability, correcting its former internal label without changing
@@ -1047,7 +1047,7 @@ release/adoption is recorded. Evidence: `run/migration-tile-trait-access-referen

 ## Custom Java tile-trait authoring

-The [authoring guide](docs/api/CUSTOM_TILE_TRAITS.md) now covers the existing name-based
+The [authoring guide](../api/CUSTOM_TILE_TRAITS.md) now covers the existing name-based
 `MultipartGenerator.registerTrait` path with a top-level Java input, separate marker and stable capability interfaces,
 an ordinary helper and no reflection. The Forge example exercises both side selections, transformed dispatch, binding,
 exact tile reuse and generated-class caching. It owns no state and derives its aggregate from the live part list;
@@ -1,13 +1,13 @@
 # Java migration divergences

 Current intentional differences from the `1.7.12` reference. This is a compatibility ledger, not a port diary.
-An unchanged implementation needs no entry. Results and port history belong in `JAVA_MIGRATION.md` and
-`JAVA_MIGRATION_HANDOFF.md`; client gaps in `JAVA_MIGRATION_MANUAL_CHECKS.md`; measurements in
-`JAVA_MIGRATION.md#phase-4b--measured-performance-pass`. Superseded decisions and the original per-port narrative remain in git history.
+An unchanged implementation needs no entry. Results and port history belong in `docs/migration/README.md` and
+`docs/migration/HANDOFF.md`; client gaps in `docs/migration/MANUAL_CHECKS.md`; measurements in
+`docs/migration/README.md#phase-4b--measured-performance-pass`. Superseded decisions and the original per-port narrative remain in git history.

 “No audited consumer” means the frozen GTNH binary inventory and consumer-source audit, not every possible
 third-party mod. Removed members can still break unaudited consumers. Check
-`JAVA_MIGRATION_COMPATIBILITY.md`, which holds both the binary inventory and the consumer-source
+`docs/migration/COMPATIBILITY.md`, which holds both the binary inventory and the consumer-source
 audit, before extending this list.

 ## Runtime and error behavior
@@ -1,4 +1,4 @@
-# Java migration — working handoff
+# Java migration - working handoff

 Start here. Work in this migration checkout on **`algent/java`**, based on `master`; inspect
 branch, status and recent commits before editing and preserve existing work. The detached review worktree is not the
@@ -6,13 +6,13 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes

 | Document | Purpose |
 | --- | --- |
-| [Plan](JAVA_MIGRATION.md) | Phase gates, API/runtime/modern-Java policy, build arrangement and the performance protocol |
-| [Compatibility](JAVA_MIGRATION_COMPATIBILITY.md) | Binary ABI inventory plus the source-level consumer audit and adoption ledger |
-| [Divergences](JAVA_MIGRATION_DIVERGENCES.md) | Intentional effective compatibility differences |
-| [Manual checks](JAVA_MIGRATION_MANUAL_CHECKS.md) | Client/release checks with concrete item examples |
-| [Java API index](docs/API.md) | Consumer entry points, guides and compiling examples |
-| [Release notes](docs/RELEASE_NOTES.md) | What breaks for consumers who rebuild, and the supported replacements |
-| [History](docs/migration/HISTORY.md) | Dated completed-port findings and reference evidence; read as needed |
+| [Plan](README.md) | Phase gates, API/runtime/modern-Java policy, build arrangement and the performance protocol |
+| [Compatibility](COMPATIBILITY.md) | Binary ABI inventory plus the source-level consumer audit and adoption ledger |
+| [Divergences](DIVERGENCES.md) | Intentional effective compatibility differences |
+| [Manual checks](MANUAL_CHECKS.md) | Client/release checks with concrete item examples |
+| [Java API index](../API.md) | Consumer entry points, guides and compiling examples |
+| [Release notes](../RELEASE_NOTES.md) | What breaks for consumers who rebuild, and the supported replacements |
+| [History](HISTORY.md) | Dated completed-port findings and reference evidence; read as needed |

 ## Current state and next target

@@ -21,7 +21,7 @@ files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has

 The agreed milestone order is the documented consumer-facing Java API, then consumer release and adoption, then final
 Scala removal; see the plan's API migration design and Phases 8-10. Per-change fixes, their regression cases and their
-recorded ABI evidence are in [the history](docs/migration/HISTORY.md); do not restate them here.
+recorded ABI evidence are in [the history](HISTORY.md); do not restate them here.

 Direct typed calls are the intended end state for supported integrations. Optional dependencies should isolate typed
 compatibility code behind presence/version checks; reflection snippets in earlier guides are temporary legacy
@@ -34,7 +34,7 @@ The old `registerParts` family also required `scala.collection.Seq`/`scala.Funct
 `registerPartFactory` compiles without Scala. Keep this gate for remaining APIs; import/bytecode checks alone are insufficient.
 Internal storage writes and reconstruction still dispatch through the old setter/loader hooks, not the Java siblings.

-The [API index](docs/API.md) orients consumers to entry points, compiling examples and migration status. Material
+The [API index](../API.md) orients consumers to entry points, compiling examples and migration status. Material
 enumeration and tile read/traversal/loading/storage APIs are also complete. No supplied consumer directly calls the
 two-argument tile occlusion hook; existing `canAddPart`/`canReplacePart` calls need no rename. GuideNH and Schematica
 have Java loading replacements, but consumer source changes, other reflection/extension contracts, releases and pack
@@ -58,9 +58,9 @@ final Scala removal and client/pack release validation.

 Extra Utilities remains an active supported consumer. UtilitiesInExcess is the intended replacement, but the support
 switch awaits approval and actual target-pack adoption. Retain existing contracts until those gates pass. The
-[overall remaining-work summary](JAVA_MIGRATION.md#remaining-work-overall) separates FMP work from downstream gates.
+[overall remaining-work summary](README.md#remaining-work-overall) separates FMP work from downstream gates.

-A separate [Phase 4b performance pass](JAVA_MIGRATION.md#phase-4b--measured-performance-pass) is planned once the API
+A separate [Phase 4b performance pass](README.md#phase-4b--measured-performance-pass) is planned once the API
 and representative extension workloads are stable, alongside consumer migration. Use fresh realistic profiles and
 repeated paired runs; distinguish FMP implementation gains from migrated-consumer gains, covering hot paths plus
 startup, transitions, rendering, network and memory costs, following the measurement protocol recorded there. The
@@ -76,7 +76,7 @@ Prefer modern syntax where it improves readability and the compilation boundary
 Scala removal. Defer a specific change if Scala parsing, compile order, ABI or downgrader/runtime support blocks it,
 recording the blocker and revisit condition. Keep the global modern-syntax setting disabled while it breaks Scala
 compilation. The build arrangement, eligibility rules and expansion constraints are in the plan's
-[modern Java readability policy](JAVA_MIGRATION.md#modern-java-readability-policy).
+[modern Java readability policy](README.md#modern-java-readability-policy).

 The initial Java API can operate over retained Scala storage and compatibility shells. Record legacy FMP uses,
 replacements, consumer releases, target-pack adoption and verification in the consumer audit. Source patches alone
@@ -219,7 +219,7 @@ also loses Scala property/indexing composition: the converted Face, Corner, Edge
 extra empty argument list before the index when recompiling, while existing bytecode remains compatible.

 **A companion object can be load-bearing without a single bytecode reference.** The inventory's 17 `MODULE$` list is
-not the whole test — check the reflective string constants too. `MultipartHelper$` is in neither the `MODULE$` list nor
+not the whole test - check the reflective string constants too. `MultipartHelper$` is in neither the `MODULE$` list nor
 any consumer's constant pool as a type, but guidenh names it as a string, so it was kept. `IconHitEffects$` was in
 neither and was dropped. Check both lists before deleting a companion.

@@ -242,7 +242,7 @@ open, then run the focused test and ABI comparison from the clean output.
 **Classes that cannot class-initialize headless make good probes.** `MultipartSaveLoad` reflects into `TileEntity`'s
 static maps through `ObfMapping` and always throws under a plain JVM. That turns "did this branch reach the loader?"
 into an assertion: returning normally proves the guard short-circuited, and `assertThrows(LinkageError.class, ...)`
-proves the other branch did reach it. Use `LinkageError`, not the exact type — the first attempt raises
+proves the other branch did reach it. Use `LinkageError`, not the exact type - the first attempt raises
 `ExceptionInInitializerError` and every later one raises `NoClassDefFoundError`, so test order would otherwise matter.

 **Where a trait member cannot be a default, use an interface static.** `TScheduledPacketPart.read` is shadowed by
@@ -324,12 +324,12 @@ composite has already invoked the real base constructor, then preserves the rema

 ## Release gaps and cleanup

- The full [manual checklist](JAVA_MIGRATION_MANUAL_CHECKS.md) is still open. The user confirmed the ProjectRed
+- The full [manual checklist](MANUAL_CHECKS.md) is still open. The user confirmed the ProjectRed
  placement crash is fixed (`36e1a58`), but that does not establish all rendering, particles, selection/collision,
  pick-block, activation or lighting behavior. The headless renderer tests cover compiled dispatch, not GPU output.
 - Existing binaries retain the runtime tile interfaces. Recompilation against raw Java mixin inputs can emit invalid
-  class/field opcodes after Forge transforms them. [Stable capability guidance](docs/api/TILE_TRAIT_ACCESS.md) covers
-  redstone, ordinary base/interface calls and slot refresh; [custom authoring guidance](docs/api/CUSTOM_TILE_TRAITS.md)
+  class/field opcodes after Forge transforms them. [Stable capability guidance](../api/TILE_TRAIT_ACCESS.md) covers
+  redstone, ordinary base/interface calls and slot refresh; [custom authoring guidance](../api/CUSTOM_TILE_TRAITS.md)
  covers marker registration, stable capabilities and transformer constraints. The server pass-through fixture does
  not cover client exclusion.
 - Run representative full-pack CPU/allocation and packaged modern-Java validation before performance/release claims.
@@ -1,19 +1,19 @@
 # Migration history

 Historical findings from the Scala-to-Java migration. Counts, next-target suggestions and outstanding work below
-describe the state at the time of each entry; use the [working handoff](../../JAVA_MIGRATION_HANDOFF.md) for current
-state and the [plan](../../JAVA_MIGRATION.md) for remaining gates. Routine sessions need not read this entire log.
+describe the state at the time of each entry; use the [working handoff](HANDOFF.md) for current
+state and the [plan](README.md) for remaining gates. Routine sessions need not read this entire log.

-The former detailed per-port handoff is also available with `git show cf8b2f9:JAVA_MIGRATION_HANDOFF.md`.
+The former detailed per-port handoff is also available with `git show cf8b2f9:docs/migration/HANDOFF.md`.
 Keep new findings here; summarize only current state and constraints in the handoff. Intentional compatibility
-differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.md).
+differences belong in the [divergence ledger](DIVERGENCES.md).

 Per-entry green-build status was removed in a later pass: superseded intermediate test counts, generated-dump
 comparisons, formatting/checkstyle results and stale "X is next" pointers. Findings, decisions, rejected options and
 ABI observations were kept. A passing build was the baseline expectation for every entry, so its absence here does not
 mean a check was skipped. The last two sections hold records moved from the retired profile and downgrader documents.

-### 2026-09-09 — Scheduler unload and inventory size regressions
+### 2026-09-09 - Scheduler unload and inventory size regressions

 - Restored the original Scala mutable-set filtering in `TickScheduler.WorldTickScheduler.postTick`, matching the
  retained-collection approach in `PacketScheduler`. Java's fail-fast set iterator threw when a scheduled callback
@@ -49,11 +49,11 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Confirmed that every non-exempt part needs at least one exclusively owned voxel. Any second write to an occupied voxel permanently changes it to `-1`, including overlap between two boxes supplied by the same part; this can make that part fail the test. Preserve this exact dynamic-tile behavior during translation unless it is changed later as an explicitly documented bug fix.
 - Completed the first behavior-preserving production conversion by replacing `IDWriter.scala` with `IDWriter.java`. All eight existing encoding cases, all 25 plain-JVM tests, the clean build, and both Java 8 Forge server checks pass unchanged.
 - Preserved the four legacy Scala function accessor descriptors as deprecated binary bridges and added direct Java `write(MCDataOutput, int)` and `read(MCDataInput)` methods. Recompiled Scala registry callers use the new primitive methods because Scala property auto-application does not apply to accessors declared in Java.
- Removed the six `IDWriter$$anonfun$setMax$*` compiler artifacts from the packaged jar. Their disappearance and replacement with Java anonymous helper classes is recorded in `JAVA_MIGRATION_DIVERGENCES.md`; the supported `IDWriter` descriptors remain link-compatible.
+- Removed the six `IDWriter$$anonfun$setMax$*` compiler artifacts from the packaged jar. Their disappearance and replacement with Java anonymous helper classes is recorded in `docs/migration/DIVERGENCES.md`; the supported `IDWriter` descriptors remain link-compatible.
 - Added a frozen Scala 2.11.5 consumer compiled against the reference dev jar. Its constructor and inherited default method call `JPartialOcclusion$class` directly, so it detects the linkage failure that freshly recompiled tests would miss.
 - Replaced `TPartialOcclusion.scala` with Java implementations of `PartialOcclusionTest` and `JPartialOcclusion`. The interface keeps its name and method descriptors, while `allowCompleteOcclusion()` is now a Java default method and the deprecated `$class` helper remains for old Scala binaries.
 - Passed all ten partial-occlusion behavior/API cases, the frozen Scala binary consumer, all 27 plain-JVM tests, a clean build, and both Java 8 Forge server checks. The existing marker-interface registration remains unchanged and continues to drive runtime tile generation.
- Completed the downstream ABI inventory by constant-pool scan of 240 mod jars in GTNH daily `2026-08-14+678`, recorded in `JAVA_MIGRATION_COMPATIBILITY.md` with the scanner in `tools/AbiScan.java` and the frozen baseline in `src/test/fixtures/abi/`. GitHub code search was rejected as an oracle because it indexes default branches only and cannot see reflection strings or closed-source consumers.
+- Completed the downstream ABI inventory by constant-pool scan of 240 mod jars in GTNH daily `2026-08-14+678`, recorded in `docs/migration/COMPATIBILITY.md` with the scanner in `tools/AbiScan.java` and the frozen baseline in `src/test/fixtures/abi/`. GitHub code search was rejected as an oracle because it indexes default branches only and cannot see reflection strings or closed-source consumers.
 - Found 27 consumer jars referencing 35 inherited types, 255 exact member descriptors, 76 other types, and 20 reflective string constants.
 - Answered open decision 2: third-party Scala traits are registered externally. ProjRed passes its own `LightMicroblock` Scala trait to `MicroblockGenerator.registerTrait`, so `registerScalaTrait` and ScalaSignature decoding must survive Phase 7.
 - Answered open decision 4: Scala runtime removal is not achievable for the first Java release. ProjRed, OpenComputers, ProjectBlue, and ForgeRelocationFMP link against 16 static methods on 8 trait `$class` helpers plus 17 companion `MODULE$` singletons.
@@ -61,7 +61,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Found zero downstream references to `IDWriter`, so its four retained Scala function accessors are not load-bearing and can be dropped.
 - Removed both speculative bridges the inventory proved dead: the four `IDWriter` Scala function accessors and the whole `JPartialOcclusion$class` helper, along with the `ReferenceScalaPartialOcclusion` fixture that only existed to verify the helper. `JPartialOcclusion` itself and both of its method descriptors are unchanged.
 - `IDWriter` now selects a carrier width instead of storing Scala closures, removing the per-call `Integer` boxing and `Function1`/`Function2` allocation that the first port had preserved. The nine encoding cases still pass unchanged.
- Established the working rule for the remaining phases: check `JAVA_MIGRATION_COMPATIBILITY.md` before writing a bridge, rather than writing one reflexively for every converted file.
+- Established the working rule for the remaining phases: check `docs/migration/COMPATIBILITY.md` before writing a bridge, rather than writing one reflexively for every converted file.
 - Ported `TCuboidPart`, `JCuboidPart` and `TCuboidPart$class` to Java, the first conversion of a trait whose `$class` helper is genuinely load-bearing. All reference descriptors are preserved, verified by diffing `javap -s` against the reference dev jar, and a frozen Scala 2.11.5 consumer whose forwarders call all four statics loads and runs against the port.
 - Found the first structural limit of the migration: Scala trait linearization cannot be reproduced by a Java interface, because a superclass method always beats an interface default on the JVM. Recompiled Scala consumers that mix `TCuboidPart` into a `TMultiPart` subclass now silently get `TMultiPart`'s empty implementations. Binary compatibility is unaffected, and `CuboidPartCharacterizationTest` carries the regression guard, but this applies to every remaining trait that overrides `TMultiPart` members and should be assumed for `TFacePart`, `TNormalOcclusion`, `TIconHitEffects` and `TItemMultiPart` as well.
 - Recorded the consequence for consumers: Scala code that recompiles must extend `JCuboidPart` or declare the overrides itself. This belongs in the release notes for the first Java release, not only in the divergence log.
@@ -90,13 +90,13 @@ mean a check was skipped. The last two sections hold records moved from the reti

 - Ported the six marker interfaces: `TSlottedPart`, `IRandomDisplayTick`, `INeighborTileChange`, `TRandomUpdateTick`, `ISidedHollowConnect` and `IMicroMaterialRender`. All six are member- and descriptor-identical to the reference, and the seven implementors and mixin tiles were diffed as well and are unchanged member for member.
 - Confirmed that five of the six were already pure abstract interfaces in bytecode with no `$class` helper, so their conversion had no bytecode consequence at all. Exactly one class left the jar: `TRandomUpdateTick$class`.
- Applied the default-versus-abstract rule to `TRandomUpdateTick.onWorldJoin` and got the failing answer: `TMultiPart` declares `onWorldJoin`, so a default would be shadowed by the superclass and the auto-registration would silently never run. It stays abstract, and implementors declare it and call `TickScheduler.loadRandomTick` themselves, which `RedstoneTorchPart` — the only implementor in this codebase — already did.
+- Applied the default-versus-abstract rule to `TRandomUpdateTick.onWorldJoin` and got the failing answer: `TMultiPart` declares `onWorldJoin`, so a default would be shadowed by the superclass and the auto-registration would silently never run. It stays abstract, and implementors declare it and call `TickScheduler.loadRandomTick` themselves, which `RedstoneTorchPart` - the only implementor in this codebase - already did.
 - Applied the bridge rule to `TRandomUpdateTick$class` and got a clean negative: no jar in the pack references `TRandomUpdateTick` in any form, and the frozen baseline contains exactly the eight `$class` helpers the inventory lists. No bridge was written, following the `IDWriter` precedent. The accepted cost is a recompiled-Scala-consumer break with no shipping consumer.
 - Found that `IMicroMaterialRender` is implemented for every part solely by `TMultiPart`'s Scala-style `world`/`x`/`y`/`z`/`getRenderBounds` accessors. Renaming any of them to a bean accessor would silently unimplement the interface, so the names are now pinned by a characterization test rather than left to reviewer attention.
 - Established that for interfaces carrying no implementation, the characterization is the shape: every member abstract and public, no superinterface, and the exact member set. That is enough to catch the two realistic failure modes, a stray default and a renamed accessor.
 - Noted that `IRedstonePart.scala` is misleadingly named and is not a marker-trait file. It carries six traits plus `RedstoneInteractions`, whose `MODULE$` is load-bearing, and was moved out of the low-risk group.
- Historical documentation gap: the ports between `TItemMultiPart` and this entry — `TEdgePart`, `Saw`, both
-  registries, `TileMultipart`, `TMultiPart`, `TickScheduler` and `BlockMultipart` — did not receive dated findings
+- Historical documentation gap: the ports between `TItemMultiPart` and this entry - `TEdgePart`, `Saw`, both
+  registries, `TileMultipart`, `TMultiPart`, `TickScheduler` and `BlockMultipart` - did not receive dated findings
  here. Use the handoff for their current status and git history for the original validation narrative; the divergence
  ledger now records only their effective compatibility differences.
 - Ported `MultipartHelper`, `MultipartHelper$` and `MultipartHelper$IPartTileConverter` to Java. All three are public-member- and descriptor-identical to the reference and the full emitted class list is unchanged, so this port neither added nor removed a class.
@@ -105,7 +105,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Confirmed that erasure does not weaken `IPartTileConverter.convert`. The cast to `T` compiles away, but the `ClassCastException` a mismatched tile produces comes from the synthetic bridge on the subclass overriding `convertMulti(T)`, which is the same mechanism Scala's `asInstanceOf[T]` relied on. It is now pinned by a test, because the code reads as though the check was lost.
 - Added five Forge server tests, doubling that suite, because most of this class cannot run headless. They cover tile construction through the ASM generator, the NBT round trip through the save/load hooks, `registerTileConverter` appending to a Scala `MutableList` from Java, and `sendDescPacket` against a loaded chunk.
 - Dropped the two commented-out blocks the reference carried, the `PlayerInstance.playersInChunk` reflection and the multi-tile `sendDescPackets`, rather than reproducing dead Scala as dead Java. The reason they existed, a missing forge access transformer, is now in the class javadoc.
- Read guidenh's actual source at `6137525` rather than inferring from its constant pool, and recorded the exact reflective member list in `JAVA_MIGRATION_COMPATIBILITY.md`. The scan could see the 20 names; only the source shows which members are looked up on them, and none of it is visible to the ABI diff.
+- Read guidenh's actual source at `6137525` rather than inferring from its constant pool, and recorded the exact reflective member list in `docs/migration/COMPATIBILITY.md`. The scan could see the 20 names; only the source shows which members are looked up on them, and none of it is visible to the ABI diff.
 - Found that `MultipartGenerator$.MODULE$` is load-bearing through reflection. `generateCompositeTile` is `private[multipart]`, so no static forwarder exists and guidenh's static attempt always misses, leaving the companion as the only route. Phase 6/7 must keep it.
 - Found that `MicroblockGenerator$.create` is matched by exact parameter types, with `MicroblockClass`'s fully qualified name string-compared. Widening a parameter or renaming the class breaks the lookup while every call site still links.
 - Verified against the already-ported `TileMultipart` that `partList_$eq(scala.collection.Seq)`, `loadParts`, `notifyTileChange` and `markRender` all survived. `partList_$eq` is a Scala `var` setter with no Java-facing equivalent and is reflectively load-bearing, so dropping it for a list mutator would have broken guidenh invisibly. It was kept.
@@ -173,7 +173,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Added an opt-in Forge/JFR workload and captured the first focused CPU/allocation baseline. With eight parts,
  `updateEntity` and `operate` allocate 184.0 and 183.9 bytes per call; generated redstone's three-query iteration
  allocates 80.5 bytes. CPU and allocation sites point to `TileMultipart.parts()` collection copies and Scala
-  redstone `IntRef`/closure traversal. Full methodology and rerun commands are in `JAVA_MIGRATION.md#phase-4b--measured-performance-pass`.
+  redstone `IntRef`/closure traversal. Full methodology and rerun commands are in `docs/migration/README.md#phase-4b--measured-performance-pass`.
 - The expanded baseline is 130 plain-JVM tests and 28 Forge server tests, all passing.

 ### 2026-08-28
@@ -522,7 +522,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  methods, their abstract/static modifiers and both binary names remain exact; no new API or default methods are
  introduced. Neither downstream audit contains a reference to this support trait.
 - The two-type ABI and both generator companions' disassembly match the reference.
- Condensed `JAVA_MIGRATION_DIVERGENCES.md` from 3,134 to 189 lines, keeping effective runtime, binary and source
+- Condensed `docs/migration/DIVERGENCES.md` from 3,134 to 189 lines, keeping effective runtime, binary and source
  differences plus one shared classfile section. Removed repeated preservation claims, validation histories and
  superseded intermediate decisions; the original narrative remains in git history. The workflow now records test
  results here and updates the divergence ledger only for a genuinely new difference.
@@ -898,7 +898,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  this history, duplicated completed-port handoff summaries were removed, and current phase/status text was refreshed.
  The manual checklist now names verified consumer items, including the inverted ProjectRed lamp requirement.

-### 2026-09-03 — composite class generation
+### 2026-09-03 - composite class generation

 - Added eight Forge characterization tests for `ASMMixinCompiler.mixinClasses`, passing on untouched Scala and
  committed first as `1c9cd65`. They execute generated JVM classes and freeze empty selection, constructor forwarding,
@@ -917,7 +917,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  9 Scala files / 1,444 nonblank Scala lines. Next: `ASMMixinCompiler.registerJavaTrait`, characterized before
  extraction; abstract mixins, side-only filtering and the wide-field defect remain separate compiler changes.

-### 2026-09-03 — Java trait rewriting
+### 2026-09-03 - Java trait rewriting

 - Added nine Forge characterization tests for `ASMMixinCompiler.registerJavaTrait`, passing against untouched Scala
  and committed first as `85ad2e4`. They freeze rejected shapes, exact input cloning, constructors, initialization,
@@ -936,7 +936,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  9 Scala files / 1,196 nonblank Scala lines. Next: assess the remaining compiler startup/model shell before selecting
  another extraction; retained ScalaSignature model bridges remain the Java-source limit.

-### 2026-09-03 — compiler startup
+### 2026-09-03 - compiler startup

 - Added seven Forge characterization tests for the `ASMMixinCompiler` singleton startup, passing against untouched
  Scala and committed first as `e9d81d6`. They execute reflective definition and transformer invocation on isolated
@@ -956,7 +956,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  malformed inherited-call casts are real but dormant for current consumers. Abstract Java mixins and Java-path side
  filtering remain required before the microblock traits can move, and will be separate behavior targets.

-### 2026-09-03 — abstract Java mixins
+### 2026-09-03 - abstract Java mixins

 - Added two Forge characterizations before changing behavior and committed them as `3556725`. They freeze the old
  abstract-input rejection before parent or method inspection and prove that concrete Java mixins already preserve
@@ -977,7 +977,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  dev config remain correct. Sources stay at 214 Java files and 9 Scala files / 1,188 nonblank Scala lines. Next:
  Java-path `@SideOnly` member filtering, characterized first as its own compiler behavior target.

-### 2026-09-03 — Java mixin side filtering
+### 2026-09-03 - Java mixin side filtering

 - Expanded the Forge Java-trait fixture against the untouched implementation and committed it first as `a481859`.
  It proves that the old Java path retained runtime-visible and runtime-invisible client annotations on a dedicated
@@ -999,7 +999,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  guard and dev config remain correct. Sources stay at 214 Java files and 9 Scala files / 1,188 nonblank Scala lines.
  Next: `microblock/MicroblockTraits.scala`, characterized before conversion.

-### 2026-09-03 — Common microblock trait implementation
+### 2026-09-03 - Common microblock trait implementation

 - Committed seven JVM and two Forge characterization tests first as `d6eb56b`. A frozen Scala 2.11.5 concrete
  `CommonMicroblockClient`, compiled under Java 8 against the unchanged jar, exercises all three trait helper bridges.
@@ -1020,7 +1020,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  files and 9 Scala files / 1,170 nonblank Scala lines. Next: `microblock/FaceMicroblockTraits.scala` implementation,
  with characterization before conversion. GPU rendering and full client selection remain on the manual checklist.

-### 2026-09-03 — Face microblock trait implementation
+### 2026-09-03 - Face microblock trait implementation

 - Committed five JVM and three Forge characterization tests first as `dc845bc`. The frozen Scala 2.11.5 face-client
  consumer was compiled under Java 8 against the untouched jar. Tests verify actual emitted face indices, position,
@@ -1041,7 +1041,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  prove per-face dispatch, not GPU output. Next: `microblock/CornerMicroblockTraits.scala` implementation, characterized
  before conversion.

-### 2026-09-03 — Corner microblock trait implementation
+### 2026-09-03 - Corner microblock trait implementation

 - Committed three JVM and three Forge characterization tests first as `82da452`. A frozen Scala 2.11.5 corner
  implementor, compiled under Java 8 against the untouched jar, pins the virtual shape setter/getter and seven-slot
@@ -1059,7 +1059,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Next: `EdgeMicroblock` in `microblock/EdgeMicroblockTraits.scala`; characterize and port the post traits separately.
  Client/GPU and full-pack validation remain on the existing manual checklist.

-### 2026-09-03 — Edge microblock trait implementation
+### 2026-09-03 - Edge microblock trait implementation

 - Committed three JVM and three Forge characterization tests first as `5e020e5`. A frozen Scala 2.11.5 implementor,
  compiled under Java 8 against the untouched jar, pins virtual shape access, byte truncation/integer overflow and the
@@ -1078,7 +1078,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  support and generated state before extraction. `PostMicroblockClient` follows separately. The existing manual
  Stone Strip / ProjectRed Red Alloy Wire and illuminated-strip checks cover the remaining client/full-pack gate.

-### 2026-09-03 — Post microblock trait implementation
+### 2026-09-03 - Post microblock trait implementation

 - Committed six JVM and four Forge characterization tests first as `afd6c69`. Frozen Scala 2.11.5 post/face
  implementors compiled under Java 8 against the untouched jar pin virtual calls, failure ordering and a real
@@ -1099,7 +1099,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Next: `PostMicroblockClient`; characterize render dispatch, lifecycle super ordering, shrink/split/reset behavior
  and size/transparency/axis tie-breaks before conversion. Client/GPU and full-pack checks remain manual.

-### 2026-09-03 — Post microblock client implementation
+### 2026-09-03 - Post microblock client implementation

 - Committed eight JVM characterization tests and one Forge test first as `47885d1`. Frozen Scala 2.11.5 client forwarders
  and lifecycle predecessors pin the exact `-1` render branch, material reuse, live second-segment changes, repeated
@@ -1120,7 +1120,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  dedicated server strips the client factory entry point; helper/geometry coverage does not establish actual client
  generation or GPU output. Next: `HollowMicroblock`, followed separately by `HollowMicroblockClient`.

-### 2026-09-03 — Hollow microblock trait implementation
+### 2026-09-03 - Hollow microblock trait implementation

 - Committed five JVM and four Forge characterization tests first as `6e807cc`, before changing production code.
  Frozen Scala 2.11.5 forwarders compiled under Java 8 against the untouched jar pin repeated tile/raw-shape reads,
@@ -1146,7 +1146,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  Added a manual hollow-cover interaction/reload check with ProjectRed Framed Red Alloy Wire and Hollow Inverted
  White Lamp Cover examples; actual client generation, GPU output and full-pack validation remain manual gates.

-### 2026-09-04 — Hollow microblock client implementation
+### 2026-09-04 - Hollow microblock client implementation

 - Committed eight JVM and one Forge characterization tests first as `c22d1ac`, before changing production code.
  Frozen Scala 2.11.5 forwarders and a real superclass predecessor pin default-mask initialization, super/read order,
@@ -1172,7 +1172,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  cover AE2 cables and ProjectRed Framed Red Alloy Wire through hollow covers. Recorded rendering commands and
  headless helper tests do not validate actual client generation or GPU/full-pack output.

-### 2026-09-04 — Micro occlusion trait implementation
+### 2026-09-04 - Micro occlusion trait implementation

 - Committed eight JVM and two Forge characterization tests first as `c709759`. Frozen Scala 2.11.5 forwarders
  compiled under Java 8 against the untouched jar pin the real super call before null/non-micro guards, repeated
@@ -1193,7 +1193,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  mask updates and failures. Retain `JMicroShrinkRender` and required Scala metadata/state/super bridges. Actual
  client generation, GPU drawing and full-pack checks remain on the existing manual checklist.

-### 2026-09-04 — Micro occlusion client state updates
+### 2026-09-04 - Micro occlusion client state updates

 - Committed six JVM and one Forge characterization tests first as `d69d12b`, against untouched production code.
  Frozen Scala 2.11.5 forwarders compiled under Java 8 pin the three real superclass predecessors, virtual recalc
@@ -1219,7 +1219,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  ProjectRed Inverted White Lamp microblocks, including a server rejoin. Headless probes do not establish actual
  client generation, GPU output or full-pack correctness; those checks remain unrecorded release gates.

-### 2026-09-04 — Packet scheduler callback regression
+### 2026-09-04 - Packet scheduler callback regression

 - Restored the original Scala mutable hash-map `foreach` traversal behind `PacketScheduler`'s Java API. Java's
  fail-fast iterator threw `ConcurrentModificationException` when a write callback scheduled another part. Keeping
@@ -1230,7 +1230,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  checked against the original Scala implementation under Java 8.
 - Formatting, test checkstyle, all four packet-interface JVM tests and all 237 Forge server tests pass.

-### 2026-09-04 — Multipart virtual tile accessor regression
+### 2026-09-04 - Multipart virtual tile accessor regression

 - Restored virtual `tile()` and `tile_$eq` dispatch throughout `TMultiPart`, matching the original Scala methods.
  Binding, coordinates/world lookup, ray tracing, harvesting and packet operations now honor part subclasses that
@@ -1239,7 +1239,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  reads that publish a replacement tile before the render update. All three failed before the fix.
 - Formatting, test checkstyle, the three new cases and all seven existing tile equality cases pass.

-### 2026-09-04 — Tick scheduler equality regression
+### 2026-09-04 - Tick scheduler equality regression

 - Restored Scala's null-safe part equality in `ChunkTickScheduler.scheduleTick` with `Objects.equals`. Distinct but
  equal parts share the original entry and callback target, and random-to-scheduled promotion updates that entry.
@@ -1249,7 +1249,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - The four touched class surfaces retain their callable member names and descriptors. The packaged inventory grows
  from 444 to 445 classes solely for the packet traversal callback; no existing class is removed.

-### 2026-09-04 — Scoped modern Java compilation
+### 2026-09-04 - Scoped modern Java compilation

 - Kept Scala 2.11.5 and joint Java compilation on Java 8. Scalac resolves `StackAnalyserLogic` through its source
  path; a separate JDK 25 task compiles that helper with `--release 21`, and JVM Downgrader supplies only Java 8
@@ -1259,11 +1259,11 @@ mean a check was skipped. The last two sections hold records moved from the reti
  398 frozen JVM consumer tests, and 237 Java 8 Forge tests. All 445 dev/release classes remain Java 8 compatible;
  with matching version metadata, only the helper changes and it exactly matches the isolated prototype. All
  retained Scala classes and 116 generated ASM dumps are identical. Source-jar contents, formatting, and checkstyle
-  pass. Evidence and reproduction commands are in `JAVA_MIGRATION.md#modern-java-readability-policy` and ignored `run/jvmdg-trial/`.
+  pass. Evidence and reproduction commands are in `docs/migration/README.md#modern-java-readability-policy` and ignored `run/jvmdg-trial/`.
 - Prefer completing useful remaining Scala behavior extractions before broad Java syntax changes. Most remaining
  Scala declarations preserve model/trait binary contracts; zero Scala is a separate compatibility decision.

-### 2026-09-04 — StackAnalyser constructor initialization
+### 2026-09-04 - StackAnalyser constructor initialization

 - Committed nine JVM characterization cases first as `929a704`, against the untouched Scala constructor.
  They cover direct constructor arguments despite overridden getters, virtual receiver/parameter pushes and
@@ -1291,7 +1291,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  case-class, product and serialization contracts. The simple model getters and full Scala shell replacement
  remain separate from useful behavior extraction.

-### 2026-09-04 — StackAnalyser constant types
+### 2026-09-04 - StackAnalyser constant types

 - Committed eight JVM characterization cases first as `89f31e3`, against the untouched Scala `Const.getType`.
  They cover all eight boxed primitive classes without numeric coercion, fresh object types for null and strings,
@@ -1318,7 +1318,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  `ASMMixinCompiler.FieldMixin.accessName`: characterize private-flag selection, owner mangling, null behavior and
  virtual accessor/failure ordering while retaining the case-class model.

-### 2026-09-04 — FieldMixin accessor names
+### 2026-09-04 - FieldMixin accessor names

 - Committed seven JVM characterization cases first as `ddeed27`, against the untouched Scala `accessName` body.
  They cover every access-flag bit and combinations, literal slash-to-dollar owner mangling, unchanged field names,
@@ -1346,7 +1346,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  `ASMMixinCompiler.MixinInfo.linearise`, with characterization of recursive parent order, repeated/diamond parents,
  virtual collection/parent dispatch and null/failure behavior before extraction.

-### 2026-09-04 — MixinInfo linearisation
+### 2026-09-04 - MixinInfo linearisation

 - Committed seven JVM characterization cases first as `d93b09d`, against the untouched Scala method. They cover
  depth-first parent order, duplicate/diamond ancestors, identity, mutable and immutable collection builders,
@@ -1365,7 +1365,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Source totals remain 224 Java files and nine Scala files / 765 nonblank lines. The next candidate is
  `ScalaSignature.Bytes.section`, preserving clamping, copy boundaries and virtual getter/failure ordering.

-### 2026-09-04 — ScalaSignature byte sections
+### 2026-09-04 - ScalaSignature byte sections

 - Committed six JVM characterization cases first as `13de853`, against the untouched Scala `Bytes.section`.
  They cover independent drop/take clamping including integer extremes, fresh empty/full/partial result arrays,
@@ -1387,7 +1387,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  `ScalaSignature.TypeRef.jName`, preserving name normalization, aliases and virtual dispatch while retaining
  path-dependent model declarations and trait bridges. Descriptor conversion remains a separate target.

-### 2026-09-04 — ScalaSignature type names
+### 2026-09-04 - ScalaSignature type names

 - Committed seven JVM characterization cases first as `ac1182e`, against the untouched Scala `TypeRef.jName`.
  They cover literal dot-to-slash conversion, exact normalized Any/AnyRef aliases, unchanged string identities,
@@ -1409,7 +1409,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  lines. Next candidate: `ScalaSignature.TypeRef.jDesc`, preserving primitive/array cases, virtual fallback and
  failure order while retaining the model overrides and trait bridges.

-### 2026-09-04 — ScalaSignature type descriptors
+### 2026-09-04 - ScalaSignature type descriptors

 - Committed seven JVM characterization cases first as `b3b3f10` against the untouched `TypeRef.jDesc`. They pin
  exact primitive/array matching, legacy reference descriptors (including Char), virtual fallback and repeated
@@ -1426,7 +1426,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  Source totals are 224 Java files and nine Scala files / 751 nonblank lines. Next: `TMethodType.jDesc` assembly,
  preserving parameter/return lookup order, nulls, failures and the retained trait/models.

-### 2026-09-04 — ScalaSignature method descriptors
+### 2026-09-04 - ScalaSignature method descriptors

 - Committed seven JVM characterization cases first as `d61aed2` against the untouched `TMethodType.jDesc`. They
  cover MethodType/ParameterlessType assembly, ordered virtual parameter info/return-type/descriptor reads,
@@ -1447,7 +1447,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  version. Sources remain 224 Java files and nine Scala files / 749 nonblank lines. Next: `ClassSymbolRef.jInterfaces`,
  retaining its List contract, virtual lookup, ordered mapping and failure behavior.

-### 2026-09-04 — ScalaSignature interface names
+### 2026-09-04 - ScalaSignature interface names

 - Committed seven JVM characterization cases first as `6ccb83f` against the untouched `ClassSymbolRef.jInterfaces`.
  They pin ClassSymbol/ObjectSymbol parent exclusion, ordered names and duplicates, the empty List singleton,
@@ -1469,7 +1469,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Sources remain 224 Java files and nine Scala files / 749 nonblank lines. Next:
  `ClassSymbolRef.toString`, preserving formatting, virtual reads and failure order.

-### 2026-09-04 — ScalaSignature class-symbol strings
+### 2026-09-04 - ScalaSignature class-symbol strings

 - Committed seven JVM characterization cases first as `1234112` against the untouched
  `ClassSymbolRef.toString`. They cover concrete ClassSymbol/ObjectSymbol runtime names, anonymous suffix trimming,
@@ -1488,7 +1488,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  version. Source totals are 224 Java files and nine Scala files / 748 nonblank lines. Next:
  `MethodSymbol.toString`, preserving formatting, virtual reads and failure order.

-### 2026-09-04 — ScalaSignature method-symbol strings
+### 2026-09-04 - ScalaSignature method-symbol strings

 - Committed seven JVM characterization cases first as `d81195a` against the untouched `MethodSymbol.toString`.
  They cover its fixed prefix for concrete and anonymous subclasses, punctuation/nulls, lowercase two's-complement
@@ -1505,7 +1505,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  version. Source totals are 224 Java files and nine Scala files / 747 nonblank lines. Next:
  `TypeRefType.jDesc`, preserving array/super routing, virtual reads and malformed-input behavior.

-### 2026-09-04 — ScalaSignature applied-type descriptors
+### 2026-09-04 - ScalaSignature applied-type descriptors

 - Committed seven JVM characterization cases first as `5493086` against the untouched `TypeRefType.jDesc`. They pin
  the array branch's first argument descriptor, fallback routing through `TypeRef.jDesc` and `jName`, two/three
@@ -1526,7 +1526,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Source totals are 224 Java files and nine Scala files / 744 nonblank lines. Next:
  `ClassSymbolRef.full`, preserving owner/name concatenation, virtual reads and failure order.

-### 2026-09-04 — ScalaSignature class-symbol full names
+### 2026-09-04 - ScalaSignature class-symbol full names

 - Committed seven JVM characterization cases first as `05c2792` against the untouched `ClassSymbolRef.full`. They
  pin concrete class/object names, punctuation, literal null full/name results, repeated owner/full/name read order,
@@ -1546,7 +1546,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Sources remain 224 Java files and nine Scala files / 744 nonblank lines. Next:
  `MethodSymbol.full`, preserving owner/name concatenation, virtual reads and failure order.

-### 2026-09-04 — ScalaSignature method-symbol full names
+### 2026-09-04 - ScalaSignature method-symbol full names

 - Committed seven JVM characterization cases first as `55f21ef` against the untouched `MethodSymbol.full`. They pin
  constructor and punctuation names, literal null full/name results, repeated owner/full/name read order, null-owner
@@ -1566,7 +1566,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Sources remain 224 Java files and nine Scala files / 744 nonblank lines. Next:
  `ClassSymbolRef.jParent`, preserving info/parent/name lookup order and failures.

-### 2026-09-04 — ScalaSignature class parent names
+### 2026-09-04 - ScalaSignature class parent names

 - Committed seven JVM characterization cases first as `6e3a301` against the untouched `ClassSymbolRef.jParent`.
  They pin ClassSymbol/ObjectSymbol results, repeated virtual info/parent/jName order, first-parent selection without
@@ -1587,7 +1587,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Sources remain 224 Java files and nine Scala files / 744 nonblank lines. Next:
  `MethodSymbol.jDesc`, preserving info/descriptor lookup order and failures.

-### 2026-09-04 — ScalaSignature method-symbol descriptors
+### 2026-09-04 - ScalaSignature method-symbol descriptors

 - Committed seven JVM characterization cases first as `16f4568` against the untouched `MethodSymbol.jDesc`. They pin
  literal and null descriptors, repeated virtual info/descriptor read order, changing uncached info results, null info,
@@ -1606,7 +1606,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Sources remain 224 Java files and nine Scala files / 744 nonblank lines. Next:
  `MethodSymbol.info`, preserving info-id/evaluation lookup order, casts and failures.

-### 2026-09-04 — ScalaSignature method-symbol info evaluation
+### 2026-09-04 - ScalaSignature method-symbol info evaluation

 - Committed seven JVM characterization cases first as `9859aa8` against the untouched `MethodSymbol.info`. They pin
  exact/null evaluated results, repeated virtual info-ID/eval order, changing uncached IDs and results, the invalid-type
@@ -1625,7 +1625,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  committed version. Sources remain 224 Java files and nine Scala files / 747 nonblank lines. Next:
  `ClassSymbolRef.info`, preserving outer/info-id/evaluation order, casts, trait bridges and failures.

-### 2026-09-04 — TileMultipart part-list accessor compatibility
+### 2026-09-04 - TileMultipart part-list accessor compatibility

 - Restored virtual `partList()` / `partList_$eq()` dispatch throughout the Java tile implementation, including
  traversal, mutation, copying, serialization and queries. Retained the optimized list traversal, captured-sequence
@@ -1638,7 +1638,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  Evidence is under ignored `run/conversion-review/`; migration-plan changes remain deferred until the review fixes
  are complete.

-### 2026-09-04 — Microblock state accessor compatibility
+### 2026-09-04 - Microblock state accessor compatibility

 - Restored virtual shape/material getters and setters for geometry, material lookup, drops, pick-block, NBT and
  description/incremental packets. The backing fields, JVM signatures and serialized formats remain unchanged.
@@ -1649,7 +1649,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  use its shape/material accessors, but no supplied consumer overriding those accessors was found. Evidence is
  under ignored `run/conversion-review/`; no migration-plan changes were made.

-### 2026-09-04 — BlockMicroMaterial property accessor compatibility
+### 2026-09-04 - BlockMicroMaterial property accessor compatibility

 - Restored virtual block, metadata, icon-transform and registry-key reads across material properties, items,
  strength, icon loading and rendering. Preserved the constructor's direct argument use, private reflective fields,
@@ -1665,7 +1665,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  accessors. These are verified extension-contract regressions, without a demonstrated current-pack gameplay
  failure. Evidence is under ignored `run/conversion-review/`; migration-plan changes remain deferred.

-### 2026-09-04 — Java material enumeration API
+### 2026-09-04 - Java material enumeration API

 - Committed two baseline cases first as `9b78099`, pinning the shared legacy array, uninitialized access, server ID
  ordering, missing slots and empty maps. Saved the pre-API jar and all 532 compiled tests before implementation.
@@ -1682,7 +1682,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  call sites and Extra Utilities' tuple-array readers have supported replacements; consumer changes, releases and
  pack adoption remain pending. Evidence is under ignored `run/migration-material-enumeration-reference/`.

-### 2026-09-04 — Java tile collection and traversal API
+### 2026-09-04 - Java tile collection and traversal API

 - Committed three baseline cases first as `5c1e760`, pinning captured Java views, lifecycle override dispatch,
  non-null binding checks and callback failure propagation. Saved the pre-API jar, source, reports, generated dumps
@@ -1704,7 +1704,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  386 member/type/reflection rows match the frozen `+678` inventory; consumer version changes do not permit bridge
  removal. Reference checkouts were not modified. Evidence: `run/migration-part-traversal-reference/`.

-### 2026-09-05 — Java tile loading/state API and documentation index
+### 2026-09-05 - Java tile loading/state API and documentation index

 - Committed four JVM and one Forge baseline cases first as `92273bd`. They pin storage aliasing/null state, binding
  and cache-hook order, stale ticking/old bindings, partial failures, exact/assignable reflection and generated slots.
@@ -1725,7 +1725,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  links. Updated the plan, ABI notes and GuideNH/Schematica adoption ledger; reference checkouts remain unchanged and
  consumer releases/pack adoption are pending. Evidence: `run/migration-part-loading-reference/`.

-### 2026-09-05 — Java collection occlusion query
+### 2026-09-05 - Java collection occlusion query

 - Committed three JVM baseline cases and stronger generated-trait assertions first as `6744f5b`. They pin pair order,
  both rejection directions, lazy null behavior, original exceptions and replacement-hook dispatch. Saved the pre-API
@@ -1747,7 +1747,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  has an explicit plan row and is the next candidate. Reference checkouts remain unchanged; client previews and
  consumer release/adoption remain separate gates. Evidence: `run/migration-part-occlusion-reference/`.

-### 2026-09-05 — Java box-versus-box occlusion query
+### 2026-09-05 - Java box-versus-box occlusion query

 - Committed three JVM baseline cases as `c7a3ed9` before changing production code. Both static and companion entries
  are checked for eager input collection, shallow snapshots, duplicate/callback order, short-circuiting, null handling
@@ -1766,7 +1766,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  27 consumers. Reference checkouts are unchanged; consumer release/adoption and manual client/pack checks remain
  pending. Next: multipart factory registration. Evidence: `run/migration-box-occlusion-reference/`.

-### 2026-09-05 — Java part factory registration
+### 2026-09-05 - Java part factory registration

 - Committed four Forge baseline cases as `e4deac8`. Real mod initialization exercises all eight old registration
  descriptors. Tests pin lazy construction, owner/array identity, partial duplicate failures, closed-state ordering,
@@ -1788,7 +1788,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  external trait migration and physical-client/pack checks remain separate. Next API-table entry: render-ID accessors.
  Evidence: `run/migration-registration-reference/`.

-### 2026-09-05 — Java render-ID accessors
+### 2026-09-05 - Java render-ID accessors

 - Committed two JVM cases and one Forge case as `3c22ab6` before changing production code. They pin the initial -1
  sentinel, shared static/companion storage, all integer values and block render-type reads. Saved the reference jar,
@@ -1805,7 +1805,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  allocation/registration/rendering remain manual gates. Next API-table entry: the tile conversion result.
  Evidence: `run/migration-render-id-reference/`.

-### 2026-09-05 — Planned measured performance follow-up
+### 2026-09-05 - Planned measured performance follow-up

 - Added Phase 4b after checking the completed focused Phase 4 work. It covers realistic consumer/pack hot paths and
  broader startup, transition, client rendering, networking and memory costs, with repeated controlled comparisons.
@@ -1814,7 +1814,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  It can overlap consumer migration once representative API/extension workloads are stable. No new performance
  measurements or speedup claims are introduced by this plan update.

-### 2026-09-05 — Named Java tile conversion result
+### 2026-09-05 - Named Java tile conversion result

 - Committed three Forge characterization cases as `7396f2d` before production edits. Both legacy entries preserve
  existing-tile identity, null/false for nonconvertible blocks (including unrelated tile entities), and bound torch
@@ -1838,7 +1838,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  Java extensions, measured performance work and actual client/pack checks remain separate gates.
  Evidence: `run/migration-tile-conversion-reference/`.

-### 2026-09-05 — Supported registered-factory lookup
+### 2026-09-05 - Supported registered-factory lookup

 - Traced Schematica `3b03ee937953` from private Scala map lookup through `MicroblockClass.create(client, materialId)`
  and NBT loading. Existing `loadPart` selects server construction, so it cannot replace that client-preview lookup.
@@ -1863,7 +1863,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  material/shape restoration, all-parts rejection and notifications must retain their staged lifecycle.
  Evidence: `run/migration-factory-lookup-reference/`.

-### 2026-09-05 — Staged Java composite-tile generation
+### 2026-09-05 - Staged Java composite-tile generation

 - Traced Schematica and GuideNH generation followed by their distinct NBT/world/position/loading/notification steps.
  `MultipartHelper.createTileFromParts` constructs and loads a server tile immediately, so it cannot replace their
@@ -1888,7 +1888,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  microblock construction and preview rendering remain manual. Next bounded task: GuideNH's existing Java microblock
  creation entry and its documented contract. Evidence: `run/migration-composite-generation-reference/`.

-### 2026-09-05 — Existing Java microblock creation contract
+### 2026-09-05 - Existing Java microblock creation contract

 - Traced GuideNH's exact companion selection and shape-only promotion. The static Java creation method already
  delegates to that implementation, so no API addition, deprecation or production behavior change was needed.
@@ -1912,7 +1912,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  Next bounded task: GuideNH's private material access versus existing public accessors.
  Evidence: `run/migration-microblock-creation-reference/`.

-### 2026-09-05 — Typed GuideNH material access
+### 2026-09-05 - Typed GuideNH material access

 - Confirmed that existing `BlockMicroMaterial.block()` / `meta()` cover GuideNH's private-field read use case. Added
  Javadocs and a compiling complete material query using direct typed part traversal, material lookup and block
@@ -1941,7 +1941,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Next bounded task: Phase 9.2 internal-boundary Javadocs with a fresh caller audit, including supported `bindPart`
  and `internalPartChange`; external Java extension guidance and the measured performance pass remain separate.

-### 2026-09-05 — Document the internal API boundary
+### 2026-09-05 - Document the internal API boundary

 - Rechecked Phase 9.2 across 28 source checkouts and active Extra Utilities compatibility. Found no external calls to the
  15 listed implementation hooks. Reviewed name collisions: WR-CBE calls its own renderer's `loadIcons`; GuideNH
@@ -1969,7 +1969,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  with generated Forge coverage. Reference consumers remain unmodified; consumer releases/adoption, physical-client
  rendering and the focused measured performance pass remain separate gates.

-### 2026-09-05 — Clarify remaining work and active consumer support
+### 2026-09-05 - Clarify remaining work and active consumer support

 - Standardized Extra Utilities references as an active supported consumer. UtilitiesInExcess remains the intended
  replacement; switching the compatibility target awaits approval and pack adoption, with the replacement's FMP
@@ -1981,7 +1981,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  changed; the existing 571 JVM / 273 Forge checkpoint remains the runtime evidence. The post-commit build verifies
  clean artifact versions under the existing workflow.

-### 2026-09-05 — Java illuminated microblock extension example
+### 2026-09-05 - Java illuminated microblock extension example

 - Traced ProjectRed `e173952e96a4`'s illuminated material/trait through registration, metadata, light aggregation and
  client halo geometry. The existing public `MicroblockGenerator.registerTrait(String)` already selects Java input;
@@ -2016,7 +2016,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  lifecycle guidance; broader transformed-tile compilation guidance and remaining audited reflection replacements
  remain separate. The performance pass, consumer release/adoption and final Scala removal gates are unchanged.

-### 2026-09-05 — Java block converter registration and lifecycle
+### 2026-09-05 - Java block converter registration and lifecycle

 - Reused existing `IPartConverter` / `registerConverter` / `convertBlock`; no API addition, descriptor change or
  production method-body change. Javadocs now describe block iterable ownership, ordered/duplicate registration,
@@ -2047,7 +2047,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  checks. Next: source-compilation guidance and safe public access for transformed tile traits. Remaining reflection
  capabilities, client validation, downstream releases/adoption and final Scala removal stay open.

-### 2026-09-05 — Stable Java access to transformed tile traits
+### 2026-09-05 - Stable Java access to transformed tile traits

 - Committed baseline `bfe5b86` before production documentation changes. Two Forge tests execute javac-compiled raw
  consumer calls: `TRedstoneTile.openConnections` fails with IncompatibleClassChangeError and `TSlottedTile.v_partMap`
@@ -2075,7 +2075,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
  released or counted as adopted. Custom tile-trait authoring examples, slot mutation, remaining reflection APIs and
  physical-client/full-pack validation remain open. Evidence: `run/migration-tile-trait-access-reference/`.

-### 2026-09-08 — Stable slot refresh for stored parts
+### 2026-09-08 - Stable slot refresh for stored parts

 - Traced OpenComputers PrintPart's state toggle at the recorded consumer revision. It changes its slot mask, clears
  every live slot entry equal to itself, calls the virtual `bindPart` chain once, then performs its own sound, part
@@ -2098,7 +2098,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Consumer source/release/adoption remain pending. Next bounded task: a custom Java tile-trait authoring example with
  generated Forge coverage; remaining audited reflection replacements and physical-client checks stay separate.

-### 2026-09-08 — Custom Java tile-trait authoring
+### 2026-09-08 - Custom Java tile-trait authoring

 - Committed baseline `d98e48f` before production documentation changes. Its Forge example registers a top-level Java
  trait by name during initialization and verifies server/client selection, stable capability dispatch, mixed-part
@@ -2119,7 +2119,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Next bounded task: expose supported button-orientation customization for Et Futurum, then cover Iguana's saw-strength
  customization. Consumer adoption, physical-client/full-pack checks and measured performance remain separate gates.

-### 2026-09-09 — Supported multipart button orientations
+### 2026-09-09 - Supported multipart button orientations

 - Inspected Et Futurum Requiem at `78a5744dfd33`. Its initialization hook reflectively obtains the two public static
  `ButtonPart` direction arrays, writes metadata `0` to `UP` and metadata `5` to `DOWN` in both directions, then catches
@@ -2141,7 +2141,7 @@ mean a check was skipped. The last two sections hold records moved from the reti
 - Next bounded task: expose supported saw-strength customization for Iguana. Consumer adoption, physical-client/full-pack
  checks and measured performance remain separate gates.

-### 2026-09-09 — Supported saw-strength mutation
+### 2026-09-09 - Supported saw-strength mutation

 - Inspected IguanaTweaksTConstruct `2.7.12` at `2bc09889d3e2`. Its post-init loop reads and writes the private
  `ItemSaw.harvestLevel` field with boxed reflection, then uses the changed value for cutting and tooltips. The
@@ -2167,9 +2167,9 @@ mean a check was skipped. The last two sections hold records moved from the reti

 ## Phase 4 focused performance records (2026-08-27 / 2026-08-28)

-Recorded results from the focused pre-optimization baseline, moved here when `JAVA_MIGRATION.md#phase-4b--measured-performance-pass` was folded
+Recorded results from the focused pre-optimization baseline, moved here when `docs/migration/README.md#phase-4b--measured-performance-pass` was folded
 into the plan. Each result is scoped to its recorded workload and revision. The reusable protocol, harness commands
-and workload description are in [the plan](../../JAVA_MIGRATION.md#phase-4b--measured-performance-pass).
+and workload description are in [the plan](README.md#phase-4b--measured-performance-pass).

 ## Baseline captured 2026-08-27

@@ -2308,9 +2308,9 @@ snapshots before publishing a replacement immutable `Seq`.

 ## JVM Downgrader integration records (2026-09-08 / 2026-09-09)

-Per-batch verification records from the scoped modern-Java integration, moved here when `JAVA_MIGRATION.md#modern-java-readability-policy`
+Per-batch verification records from the scoped modern-Java integration, moved here when `docs/migration/README.md#modern-java-readability-policy`
 was folded into the plan. The build arrangement, eligibility rules, fastutil decision and limits are in
-[the plan](../../JAVA_MIGRATION.md#modern-java-readability-policy).
+[the plan](README.md#modern-java-readability-policy).

 ### Per-batch results

@@ -84,14 +84,14 @@ entries complete.
 | [ ] | Join a server whose material set differs from the client | In disposable client/server instances, add `"minecraft:coal_ore"` only to the server's `microblocks.cfg` | The client is disconnected with the missing material list, not a crash | `readIDMap` |
 | [ ] | Join a server whose multipart type set differs from the client | Setup-only: use a small test addon that registers a part on only one side; stock consumer removal may be rejected earlier by Forge's mod handshake | The client is disconnected with the ordered missing-part list, not a crash | `MultipartCPH.handlePartRegistration` |

-The [Java illuminated extension example](docs/api/MICROBLOCK_EXTENSIONS.md) has dedicated-server and headless halo
+The [Java illuminated extension example](../api/MICROBLOCK_EXTENSIONS.md) has dedicated-server and headless halo
 coverage. When adopting it in ProjectRed, rerun the illuminated shape/lighting checks above on a physical client,
 including hollow connector widths and all sides, pass filtering and the existing halo queue/configuration. Neither
 its callback-side input tests nor its retained client-body probe validates actual client generation or GPU output.

 ## Not yet covered anywhere

- [ ] A focused pre-optimization CPU/allocation baseline now exists in `JAVA_MIGRATION.md#phase-4b--measured-performance-pass`. A representative
+- [ ] A focused pre-optimization CPU/allocation baseline now exists in `docs/migration/README.md#phase-4b--measured-performance-pass`. A representative
  full-pack capture and the matching post-optimization comparison still need to be performed. Example setup: a loaded
  chunk containing many AE2 cables, ProjectRed wires/lamps and assorted Forge Multipart microblocks.
 - [ ] Shape-specific microblock NBT and packet payloads. Core `Microblock` shape/material NBT, description bytes and
@@ -117,7 +117,7 @@ translation keys; these are examples for running the checks, not claims that the

 ## Converter integration follow-up

-The [converter guide](docs/api/BLOCK_CONVERTERS.md) and Forge fixtures establish registration, discarded probes,
+The [converter guide](../api/BLOCK_CONVERTERS.md) and Forge fixtures establish registration, discarded probes,
 committed callback order and example state round trips. Before adopting consumer changes:

 - [ ] On a physical client/server, preview and cancel conversion of Chisel torches, OpenComputers cables/prints,
@@ -136,7 +136,7 @@ committed callback order and example state round trips. Before adopting consumer
  face/framed wires with face covers and edge blockers on a physical client/server, including part changes and moves.
  Concrete setup: ProjectRed **Red Alloy Wire** and **Framed Red Alloy Wire** with Stone Covers and Stone Strips.
 - [ ] Verify consumer bytecode uses the stable interface/base owner rather than raw transformed trait class calls or
-  fields. The [Forge fixture](docs/api/TILE_TRAIT_ACCESS.md) proves server linkage, not all client-side capabilities.
+  fields. The [Forge fixture](../api/TILE_TRAIT_ACCESS.md) proves server linkage, not all client-side capabilities.
  This is a `javap`/ASM inspection check; no in-game item exercises the bytecode owner directly.
 - [ ] Rebuild OpenComputers `PrintPart.toggleState` using `tile.refreshPartSlots(this)`, then exercise inactive/active
  and button modes on client/server. Confirm old slots clear, new slots occupy, rejected changes leave caches intact,
@@ -40,18 +40,18 @@ Java-trait rewriting and compiler startup also delegate to Java helpers. Abstrac
 side-only filtering are complete; multiple Scala-trait inheritance still needs its metadata. Retain trait
 state/accessor/super bridges and the compiler/signature/analyser model shells.

-Start with [JAVA_MIGRATION_HANDOFF.md](JAVA_MIGRATION_HANDOFF.md) for the exact source/test baseline, workflow and
-Java-source limitations. Read both the [ABI inventory](JAVA_MIGRATION_COMPATIBILITY.md) and
-[consumer audit](JAVA_MIGRATION_COMPATIBILITY.md) before changing compatibility surfaces. Completed-target evidence
-is in [the history](docs/migration/HISTORY.md); the [divergence ledger](JAVA_MIGRATION_DIVERGENCES.md) records only
+Start with [the working handoff](HANDOFF.md) for the exact source/test baseline, workflow and
+Java-source limitations. Read both the [ABI inventory](COMPATIBILITY.md) and
+[consumer audit](COMPATIBILITY.md) before changing compatibility surfaces. Completed-target evidence
+is in [the history](HISTORY.md); the [divergence ledger](DIVERGENCES.md) records only
 effective compatibility differences.

 The source-only consumer guards, ordered tile lifecycle/NBT/packet fixtures and generated Scala/Java trait fixtures
 are in place. Schematica's private registry-map view is restored. The tile equality/callback regressions and the
 generated client-render dispatch crash are fixed; the user confirmed placement no longer crashes. Broader
-[manual client checks](JAVA_MIGRATION_MANUAL_CHECKS.md) and full-pack profiling remain release gates.
+[manual client checks](MANUAL_CHECKS.md) and full-pack profiling remain release gates.

-Focused traversal/redstone allocation improvements are recorded in [the profile](JAVA_MIGRATION.md#phase-4b--measured-performance-pass).
+Focused traversal/redstone allocation improvements are recorded in [the profile](README.md#phase-4b--measured-performance-pass).
 GTNHLib/UniMixins remain conditional on concrete need. Removing Scala from FMP remains the final target, gated by
 released consumer migrations and retirement of FMP's own Scala-dependent implementation.

@@ -77,8 +77,8 @@ verify that the replacement has migrated the relevant FMP contracts before remov

 GTNHLib/fastutil, UniMixins, a new generator design and further mechanical Scala-shell extraction are conditional
 work, not mandatory tasks to add without a concrete need. The existing generator is retained. See the detailed
-phases below, [consumer adoption ledger](JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger),
-[manual checklist](JAVA_MIGRATION_MANUAL_CHECKS.md) and [performance protocol](JAVA_MIGRATION.md#phase-4b--measured-performance-pass).
+phases below, [consumer adoption ledger](COMPATIBILITY.md#java-api-adoption-ledger),
+[manual checklist](MANUAL_CHECKS.md) and [performance protocol](README.md#phase-4b--measured-performance-pass).

 ## Scope and compatibility target

@@ -122,7 +122,7 @@ switch. A JDK 25 task compiles the helper with `--release 21`; JVM Downgrader su
 Forge and both packaged jars. Scala 2.11.5 and joint Scala/Java compilation stay on Java 8. The checkpoint passed
 normal/clean builds, frozen consumers and Forge tests with unchanged retained Scala classes and generated tile
 dumps. The arrangement, eligibility rules and limits are below; per-batch verification records are in
-[the history](docs/migration/HISTORY.md).
+[the history](HISTORY.md).

 - Prefer clearer pattern matching, switch expressions and local type inference where supported and appropriate;
  retain explicit types or ordinary control flow when they communicate the intent better.
@@ -258,7 +258,7 @@ The source and bytecode audit identified these allocation patterns; the named po
 The focused Forge/JFR baseline confirmed both risks. With eight parts, `updateEntity` and `operate` allocated about 184
 bytes per call, while a three-query redstone iteration allocated 80.5 bytes. The completed ports reduce the normal
 paths to effectively zero measured allocation; these remain focused measurements, not whole-pack TPS. See
-`JAVA_MIGRATION.md#phase-4b--measured-performance-pass`.
+`docs/migration/README.md#phase-4b--measured-performance-pass`.

 ### Runtime code generation is architectural, not incidental

@@ -413,25 +413,25 @@ Every implementation phase follows the same test-first gate:

 If a characterization test captures a confirmed bug that the port intentionally fixes, record it in the divergence log and change that expectation in a separate, explicit bug-fix step. This prevents accidental changes from being presented as fixes.

-### Phase 0 — Freeze and measure the reference behavior
+### Phase 0 - Freeze and measure the reference behavior

 - [x] Produce and retain a reference dev jar from `f10595d` or the selected migration base.
 - [x] Dump the public/protected JVM API and important generated tile class shapes.
 - [x] Inventory downstream mods that compile against or reflect into ForgeMultipart. See
-  `JAVA_MIGRATION_COMPATIBILITY.md`.
+  `docs/migration/COMPATIBILITY.md`.
 - [x] Record source-level consumers of part IDs, NBT, packets, registration order, reflection, and lifecycle behavior.
 - [ ] Freeze representative part IDs, NBT trees, packet bytes, registration order, and lifecycle behavior as tests.
 - [x] Add a Java-8-compatible JUnit/Jupiter setup to the existing Gradle `test` task.
 - [x] Add a separate Forge integration-test source set/runner for behavior that cannot execute in a plain JVM.
 - [x] Write the first characterization suite against the untouched Scala implementation.
- [x] Create a remaining manual compatibility checklist for rendering, input, and other behavior that cannot be asserted reliably by the automated harness. See `JAVA_MIGRATION_MANUAL_CHECKS.md`.
+- [x] Create a remaining manual compatibility checklist for rendering, input, and other behavior that cannot be asserted reliably by the automated harness. See `docs/migration/MANUAL_CHECKS.md`.
 - [x] Capture representative CPU and allocation profiles before optimization work. See
-  `JAVA_MIGRATION.md#phase-4b--measured-performance-pass`.
+  `docs/migration/README.md#phase-4b--measured-performance-pass`.
 - [x] Start a divergence log.

 Exit condition: there is a reproducible behavior and ABI baseline, the test layers run in CI or an equivalent repeatable command, and the initial suite passes against the Scala implementation.

-### Phase 1 — Add infrastructure only when first needed
+### Phase 1 - Add infrastructure only when first needed

 - [ ] Add GTNHLib with a pack-aligned version when the first Java migration or data-structure change uses it.
 - [ ] Enable UniMixins when the first fixed class transformation is introduced.
@@ -440,7 +440,7 @@ Exit condition: there is a reproducible behavior and ABI baseline, the test laye

 Exit condition: dependencies and loaders are present with no unintended gameplay behavior change.

-### Phase 2 — Establish the Java-first API and compatibility bridges
+### Phase 2 - Establish the Java-first API and compatibility bridges

 - [x] Inventory every public Scala descriptor and compiler-generated entry point used by downstream code.
 - [x] Add ABI snapshots and compiled consumer fixtures before changing public descriptors.
@@ -456,15 +456,15 @@ keeps its `scala.Tuple2` array while Extra Utilities still uses it; the new API

 Exit condition: new code can use a clean Java API while existing supported binaries still link through the deprecated surface.

-### Phase 3 — Convert low-coupling code
+### Phase 3 - Convert low-coupling code

 Status: **complete.** The low-risk queue is empty. All eight load-bearing `$class` helpers are Java with their bridges
 retained, as are both registries, the central part/tile types, scheduler/helper utilities, `BlockMultipart` and
 `MultipartRenderer`. Each leaf group was characterized before conversion, `JavaConversions` was replaced with explicit
 Java collections or controlled adapters, and iteration order and null behavior were preserved throughout. Per-type
-evidence is in [the history](docs/migration/HISTORY.md).
+evidence is in [the history](HISTORY.md).

-### Immediate compatibility gate — complete
+### Immediate compatibility gate - complete

 Status: **complete.** Every source-only constraint that can silently fail now has an automated structural or
 behavioral guard. Schematica's reflective `MultiPartRegistry$` type-map view is restored with its exact field name and
@@ -474,7 +474,7 @@ Galacticraft's name-only `registerMaterial` lookup. `TileMultipart` order and li
 are compact mixed-part NBT/description-packet fixtures and one generated Scala trait, one Java trait and
 representative pass-through interfaces.

-### Phase 4 — Convert measured hot paths
+### Phase 4 - Convert measured hot paths

 Status: **complete for the measured targets.** Traversal, redstone queries, recipe scans and the generated
 `TSlottedTile` slot scan were characterized, then rewritten without per-call collection allocation, closure
@@ -494,7 +494,7 @@ and improved throughput by 20.3% with an identical checksum.

 Exit condition: identified steady-state Scala allocation sites are removed with compatible results.

-### Phase 4b — Measured performance pass
+### Phase 4b - Measured performance pass

 Status: **planned.** Phase 4's focused historical results are complete; they do not establish current whole-pack
 performance. Re-profile the corrected Java branch and representative consumer integrations, then improve the measured
@@ -578,8 +578,8 @@ The local server EULA must already contain `eula=true`. From PowerShell at the r
 The property is quoted because PowerShell otherwise splits the dotted Gradle property. Normal
 `runFunctionalTestServer` runs are unchanged. Profile mode overwrites these ignored files:

- `run/server/forgemultipart-profile.txt` — exact timings and per-thread allocation counts;
- `run/server/forgemultipart-baseline.jfr` — JFR CPU, allocation-site and GC events.
+- `run/server/forgemultipart-profile.txt` - exact timings and per-thread allocation counts;
+- `run/server/forgemultipart-baseline.jfr` - JFR CPU, allocation-site and GC events.

 ```powershell
 jfr summary run/server/forgemultipart-baseline.jfr
@@ -595,9 +595,9 @@ The fixture uses Zulu OpenJDK 8, eight parts per tile, 1,000,000 warm-up iterati
 iterations per phase, covering `updateEntity`, `operate`, `lightValue`, `getTile` and `redstoneQueries`. The checksum
 consumes all observable work. Allocation bytes come from HotSpot's per-thread allocation counter, not from sampled
 JFR events; JFR remains the source for CPU samples and allocation-site ranking. Recorded results for the Phase 4
-focused baseline are in [the history](docs/migration/HISTORY.md).
+focused baseline are in [the history](HISTORY.md).

-### Phase 5 — Convert built-in tile traits through the existing Java path
+### Phase 5 - Convert built-in tile traits through the existing Java path

 Status: **complete.** Traits were converted in small related groups behind characterization of the generated
 interface, super dispatch, field accessors, initialization, copying, lifecycle callbacks and class caching, starting
@@ -610,7 +610,7 @@ for a registered Java trait extending another registered Java trait, explicit Ja
 runtime-only fields that must not participate in generated `copyFrom`. The generated runtime interfaces and class
 cache remain reference-identical; pass-through-interface coverage remains green.

-### Phase 6 — Convert multipart core and microblocks
+### Phase 6 - Convert multipart core and microblocks

 Status: runtime behavior for core code, factories, ordinary helpers and common/face/corner/edge/post/hollow/occlusion
 microblock traits is Java. The remaining Scala trait declarations retain inheritance, state/accessor and super-call
@@ -626,7 +626,7 @@ not an instruction to repeat completed ports; completed per-type evidence is in

 Exit condition: normal runtime implementation is Java; any remaining Scala is isolated to compatibility or ASM support.

-### Phase 7 — Port the ASM subsystem last
+### Phase 7 - Port the ASM subsystem last

 - [x] Freeze structural and behavioral fixtures for generated classes before changing the compiler.
 - [ ] Translate the existing compiler/generator into readable Java while preserving emitted class shapes and cache keys.
@@ -651,13 +651,13 @@ Exit condition: the composition subsystem is maintainable Java with behavior and
 - [ ] Refresh `README.md` for the Java-first codebase while retaining Scala IDE guidance for any sources that remain.
 - [ ] Move the durable migration documents under `docs/migration/` and decide whether the historical running plan is
  archived or removed before merge.
- [ ] Complete and record the relevant checks in `JAVA_MIGRATION_MANUAL_CHECKS.md` against a representative client and
+- [ ] Complete and record the relevant checks in `docs/migration/MANUAL_CHECKS.md` against a representative client and
  GTNH pack before release.

 Exit condition: source layout, contributor guidance and durable migration documentation match the codebase being
 merged, and all release-required manual checks have recorded results.

-### Phase 8 — Remove FMP's Scala implementation and dependencies after consumer migration
+### Phase 8 - Remove FMP's Scala implementation and dependencies after consumer migration

 Status: **planned, gated by consumer adoption.** The inventory showed shipping mods linking against trait helpers,
 companion singletons and Scala descriptors, plus ProjectRed registering an external Scala trait. The first release
@@ -682,7 +682,7 @@ inputs, storage, models and compiler support must be replaced or retired before
 Exit condition: FMP builds and runs without its own Scala requirement, and the supported target-pack integrations
 pass against that artifact. Any unfinished gate keeps the corresponding compatibility support in place.

-### Phase 9 — Deprecate the Scala-shaped API and mark the internal boundary
+### Phase 9 - Deprecate the Scala-shaped API and mark the internal boundary

 Status: **in progress: all ten Phase 9.1 table entries and Phase 9.2 are complete; broader extension/API guidance remains.**
 This phase does not redesign the API. A surface audit against all 28 consumer checkouts found the
@@ -699,23 +699,23 @@ Apply siblings, deprecations and internal-marker javadoc together when the relev
 Most implementations are already Java; remaining work is at the specific boundaries below. Keep unrelated API
 changes separate from mechanical compiler extraction, and do not add a deprecation without its replacement.

-#### 9.1 — Scala-typed signatures
+#### 9.1 - Scala-typed signatures

 Each row keeps its existing descriptor for binary compatibility and gains a Java-shaped sibling. The registry's
 existing Java `registerParts` overload still required Scala during javac resolution; `registerPartFactory` avoids it.

 | Deprecate | Java-shaped replacement | Notes |
 | --- | --- | --- |
-| `TileMultipart.partList(): scala.collection.Seq` | `jPartList(): java.util.List` | Getter deprecated; captured-sequence view documented in the [guide and compiling example](docs/api/PART_TRAVERSAL.md) |
-| `MultiPartRegistry.registerParts(IPartFactory2, scala.collection.Seq)` and companion entry | `registerPartFactory(IPartFactory2, String...)` | Implemented over existing Java registration; distinct name compiles without Scala. [Guide and example](docs/api/PART_REGISTRATION.md) also cover the retained Boolean/function adapters and their migration |
-| `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | `materialCount(): int` plus existing `materialName(int)` and `getMaterial(int)` | Implemented with static/companion deprecation; [guide and compiling example](docs/api/MATERIAL_ENUMERATION.md). Consumer release/adoption remains pending |
+| `TileMultipart.partList(): scala.collection.Seq` | `jPartList(): java.util.List` | Getter deprecated; captured-sequence view documented in the [guide and compiling example](../api/PART_TRAVERSAL.md) |
+| `MultiPartRegistry.registerParts(IPartFactory2, scala.collection.Seq)` and companion entry | `registerPartFactory(IPartFactory2, String...)` | Implemented over existing Java registration; distinct name compiles without Scala. [Guide and example](../api/PART_REGISTRATION.md) also cover the retained Boolean/function adapters and their migration |
+| `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | `materialCount(): int` plus existing `materialName(int)` and `getMaterial(int)` | Implemented with static/companion deprecation; [guide and compiling example](../api/MATERIAL_ENUMERATION.md). Consumer release/adoption remains pending |
 | `TileMultipart.operate(scala.Function1<TMultiPart, BoxedUnit>)` | `forEachPart(java.util.function.Consumer<TMultiPart>)` | Implemented through the legacy virtual hook; preserves captured traversal, detached-part filtering and callback failures. Lifecycle still calls `operate` |
-| `TileMultipart.occlusionTest(scala.collection.Seq, TMultiPart)` | `testOcclusion(Collection<? extends TMultiPart>, TMultiPart)` | Implemented with an input snapshot and legacy virtual dispatch, including generated partial occlusion; [guide](docs/api/OCCLUSION.md). Distinct Java name avoids Scala overload resolution |
-| `NormalOcclusionTest.apply(scala.collection.Traversable<Cuboid6>, scala.collection.Traversable<Cuboid6>)` and companion entry | `testBoxes(Iterable<? extends Cuboid6>, Iterable<? extends Cuboid6>)` | Implemented over the existing Java loop; both inputs snapshotted before geometry tests. [Guide and compiling example](docs/api/OCCLUSION.md#box-versus-box-queries). ForgeRelocationFMP/OpenComputers adoption remains pending |
-| `TileMultipart.loadParts(scala.collection.Iterable)` | `loadPartList(Collection<TMultiPart>)` | Implemented through the legacy virtual hook; binding, world notifications, input iteration and partial failure retained. [Loading guide](docs/api/PART_LOADING.md) |
+| `TileMultipart.occlusionTest(scala.collection.Seq, TMultiPart)` | `testOcclusion(Collection<? extends TMultiPart>, TMultiPart)` | Implemented with an input snapshot and legacy virtual dispatch, including generated partial occlusion; [guide](../api/OCCLUSION.md). Distinct Java name avoids Scala overload resolution |
+| `NormalOcclusionTest.apply(scala.collection.Traversable<Cuboid6>, scala.collection.Traversable<Cuboid6>)` and companion entry | `testBoxes(Iterable<? extends Cuboid6>, Iterable<? extends Cuboid6>)` | Implemented over the existing Java loop; both inputs snapshotted before geometry tests. [Guide and compiling example](../api/OCCLUSION.md#box-versus-box-queries). ForgeRelocationFMP/OpenComputers adoption remains pending |
+| `TileMultipart.loadParts(scala.collection.Iterable)` | `loadPartList(Collection<TMultiPart>)` | Implemented through the legacy virtual hook; binding, world notifications, input iteration and partial failure retained. [Loading guide](../api/PART_LOADING.md) |
 | `TileMultipart.partList_$eq(scala.collection.Seq)` | `setPartList(List<TMultiPart>)` | Implemented through the legacy setter; Java list copied without binding, null sentinel supported. GuideNH's old reflective name remains supported |
-| `TileMultipart.renderID()` / `renderID_$eq(int)` and companion entries | `getRenderID()` / `setRenderID(int)` | Implemented over the same global value; four legacy entries deprecated. [Guide and compiling example](docs/api/RENDER_ID.md). Reading does not initialize the client renderer |
-| `TileMultipart.getOrConvertTile2(): scala.Tuple2<TileMultipart, Object>` and companion entry | `getOrConvertTileResult(World, BlockCoord): TileConversionResult` with `getTile()` / `isConverted()` | Implemented over the retained tuple path; [guide and compiling example](docs/api/TILE_CONVERSION.md) distinguish existing tiles, uninstalled placeholders and failed conversion. No audited direct tuple caller |
+| `TileMultipart.renderID()` / `renderID_$eq(int)` and companion entries | `getRenderID()` / `setRenderID(int)` | Implemented over the same global value; four legacy entries deprecated. [Guide and compiling example](../api/RENDER_ID.md). Reading does not initialize the client renderer |
+| `TileMultipart.getOrConvertTile2(): scala.Tuple2<TileMultipart, Object>` and companion entry | `getOrConvertTileResult(World, BlockCoord): TileConversionResult` with `getTile()` / `isConverted()` | Implemented over the retained tuple path; [guide and compiling example](../api/TILE_CONVERSION.md) distinguish existing tiles, uninstalled placeholders and failed conversion. No audited direct tuple caller |

 Explicitly **not** renamed: `TMultiPart.world()`, `x()`, `y()`, `z()`, and `tile()`. These carry Scala accessor naming
 but no Scala type, so renaming is cosmetic churn across 27 consumers with no compatibility or performance payoff.
@@ -726,19 +726,19 @@ same-name overload there invites a silent wrong-overload bind.
  recursive forwarding as required by the API migration design.
 - [x] Add and document `materialCount()` with existing indexed lookups; retain and deprecate both `getIdMap()` entries.
 - [x] Document `jPartList()` and add `forEachPart(Consumer)`; deprecate the legacy getter/callback entries while retaining
-  their override dispatch. JVM and generated-tile Forge cases cover the [documented contract](docs/api/PART_TRAVERSAL.md).
+  their override dispatch. JVM and generated-tile Forge cases cover the [documented contract](../api/PART_TRAVERSAL.md).
 - [x] Add Java loading and storage assignment, with legacy override/reflection coverage, explicit ownership and
-  lifecycle contracts, and generated server/client tile checks; [guide](docs/api/PART_LOADING.md), [API index](docs/API.md).
+  lifecycle contracts, and generated server/client tile checks; [guide](../api/PART_LOADING.md), [API index](../API.md).
 - [x] Add `testOcclusion(Collection, candidate)` with snapshot ownership, subtype inputs, legacy hook dispatch and
-  generated partial-occlusion coverage; [guide and compiling example](docs/api/OCCLUSION.md).
+  generated partial-occlusion coverage; [guide and compiling example](../api/OCCLUSION.md).
 - [x] Add direct `testBoxes(Iterable, Iterable)` with eager input snapshots, ordered intersection callbacks and retained
-  static/companion bridges; [migration guide](docs/api/OCCLUSION.md#box-versus-box-queries).
+  static/companion bridges; [migration guide](../api/OCCLUSION.md#box-versus-box-queries).
 - [x] Add `registerPartFactory(IPartFactory2, String...)`, deprecate the remaining Scala sequence entries, and document
  initialization/factory/payload contracts with a compiling example and real Forge initialization coverage.
 - [x] Add Java render-ID accessors with shared global-state/sentinel checks, retained static/companion entries and
-  explicit client initialization versus assignment semantics; [guide](docs/api/RENDER_ID.md).
+  explicit client initialization versus assignment semantics; [guide](../api/RENDER_ID.md).
 - [x] Add the named tile conversion result, preserving both tuple descriptors and documenting placeholder versus
-  installed-tile lifecycle; [guide](docs/api/TILE_CONVERSION.md). All ten table entries now have replacements.
+  installed-tile lifecycle; [guide](../api/TILE_CONVERSION.md). All ten table entries now have replacements.
 - [x] For these table siblings, compile external Java examples with Scala excluded from the compile classpath before
  finalizing names. The proposed `loadParts(Collection)` overload required `scala.collection.Iterable` during javac
  overload resolution; the implemented `loadPartList(Collection)` avoids that dependency. Apply this gate to the
@@ -747,17 +747,17 @@ same-name overload there invites a silent wrong-overload bind.
 - [x] Mark the legacy table entries above `@Deprecated` with javadoc naming a working replacement.
 - [x] Confirm every original descriptor still exists in the ABI fixture after these table changes.
 - [x] Document converter registration, candidate ownership and committed lifecycle with a compiling Java example
-  and registry/Forge characterization; [guide](docs/api/BLOCK_CONVERTERS.md).
+  and registry/Forge characterization; [guide](../api/BLOCK_CONVERTERS.md).
 - [x] Characterize raw Java tile-trait linkage failures and document stable interface/base access with a compiling
-  example; [guide](docs/api/TILE_TRAIT_ACCESS.md).
+  example; [guide](../api/TILE_TRAIT_ACCESS.md).
 - [x] Add a supported `refreshPartSlots` operation for OpenComputers' live slot-array mutation, preserving equality,
-  virtual bind dispatch, storage/ownership and caller-controlled notification behavior; [guide](docs/api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask).
+  virtual bind dispatch, storage/ownership and caller-controlled notification behavior; [guide](../api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask).
 - [x] Document custom Java tile-trait authoring with a compiling marker/trait/capability example, registration and
-  state/lifecycle contracts, and generated server/client Forge coverage; [guide](docs/api/CUSTOM_TILE_TRAITS.md).
+  state/lifecycle contracts, and generated server/client Forge coverage; [guide](../api/CUSTOM_TILE_TRAITS.md).
 - [ ] Document the supported API with compiling usage examples and an old-to-new migration guide. Validate Java
  subclasses and generated extensions on the actual Forge path, including both sides where relevant.

-#### 9.2 — Mark the internal boundary
+#### 9.2 - Mark the internal boundary

 Scala's `private[multipart]` compiles to public. As a result the published surface currently advertises implementation
 hooks as though they were API, and a consumer author cannot distinguish `addPart` from `addPart_do`. This is a more
@@ -767,7 +767,7 @@ deprecation, and no new dependency for a marker annotation.
 Completed with a fresh 2026-09-05 consumer audit covering 28 source checkouts and active Extra Utilities compatibility:
 **no external calls to these FMP members were found**. The installed `+719` binary scan retains the same baseline.
 Javadocs on the declarations below and the five matching material-registry companion bridges mark them internal;
-see the [API boundary guide](docs/API.md#supported-api-and-internal-hooks).
+see the [API boundary guide](../API.md#supported-api-and-internal-hooks).

 `TileMultipart.addPart_impl`, `addPart_do`, `remPart_impl`, `writeAddPart`, `partAdded`, `partRemoved`, `from`,
 `copyFrom`, `loadFrom`, `setValid`; `MicroMaterialRegistry.setupIDMap`,
@@ -802,7 +802,7 @@ Exit condition: every Scala-typed public entry has a documented Java-shaped repl
 it, supported extension paths have buildable examples and Forge coverage, implementation-hook members are documented
 as internal, and the retained ABI fixture is unchanged.

-### Phase 10 — Upstream consumer cleanup
+### Phase 10 - Upstream consumer cleanup

 Status: **planned, required for final Scala removal.** Individual migrations can start as soon as their supported
 Java replacements exist. They need not wait for all internal source conversion; their release and pack adoption
@@ -833,8 +833,8 @@ does not close a row, and scans must distinguish a consumer's own Scala code fro
 | Consumer | What FMP is currently forced to preserve | Upstream fix | Can start |
 | --- | --- | --- | --- |
 | ProjectRed | Runtime Scala-signature decoding and external trait registration, reached through `MicroblockGenerator.registerTrait(classOf[LightMicroblock])` | Rewrite the ~60-line `LightMicroblock` trait as a Java mixin registered through the `registerJavaTrait` path | FMP compiler prerequisites complete; consumer rewrite and release remain |
-| Schematica | Private Scala-mangled field `codechicken$multipart$MultiPartRegistry$$typeMap`, cast to `scala.collection.mutable.Map` | `MultiPartRegistry.getPartFactory(String)` is implemented; [guide and example](docs/api/FACTORY_LOOKUP.md). Schematica replaces map/Option lookup with the public method and retains its microblock creation/rejection policy | FMP lookup ready; consumer patch/release/adoption pending |
-| GuideNH | Companion `MultipartGenerator$.MODULE$.generateCompositeTile` and `MicroblockGenerator$.create`; `partList_$eq(scala.collection.Seq)`; mixin into private `BlockMicroMaterial.block` and `.meta` | Direct Java tile generation/loading, microblock creation and existing `block()` / `meta()` access are documented/tested; [typed material query](docs/api/MATERIAL_ACCESS.md). Remove reflection/accessor mixins when migrating | These FMP paths ready; broader consumer migration/release/adoption pending |
+| Schematica | Private Scala-mangled field `codechicken$multipart$MultiPartRegistry$$typeMap`, cast to `scala.collection.mutable.Map` | `MultiPartRegistry.getPartFactory(String)` is implemented; [guide and example](../api/FACTORY_LOOKUP.md). Schematica replaces map/Option lookup with the public method and retains its microblock creation/rejection policy | FMP lookup ready; consumer patch/release/adoption pending |
+| GuideNH | Companion `MultipartGenerator$.MODULE$.generateCompositeTile` and `MicroblockGenerator$.create`; `partList_$eq(scala.collection.Seq)`; mixin into private `BlockMicroMaterial.block` and `.meta` | Direct Java tile generation/loading, microblock creation and existing `block()` / `meta()` access are documented/tested; [typed material query](../api/MATERIAL_ACCESS.md). Remove reflection/accessor mixins when migrating | These FMP paths ready; broader consumer migration/release/adoption pending |
 | Et Futurum Requiem | Mutable static `int[] ButtonPart.metaSideMap` and `sideMetaMap` must stay public and mutable | `ButtonPart.setOrientation(int, ForgeDirection)` is implemented and documented; Et Futurum adopts it | FMP API ready; consumer patch/release/adoption pending |
 | IguanaTweaksTConstruct | Private `ItemSaw.harvestLevel` field name and type | `ItemSaw.setHarvestLevel(int)` is implemented and documented; Iguana uses it before ForgeMicroblock post-init | FMP API ready; consumer lifecycle/source patch, release and adoption pending |
 | Galacticraft | Selects the first public method named `registerMaterial` without checking its signature, so FMP cannot add any overload of that name | Call `registerMaterial` directly from gated compatibility code; exact-signature reflection is an interim hardening option | Existing public API; consumer migration can start |
@@ -848,12 +848,12 @@ ProjectRed's `LightMicroblock` is the audited external constraint on retiring ru
 Its Java rewrite removes that external dependency only after the updated consumer is released into the pack;
 decoder removal also requires retiring internal Scala trait inputs and resolving retained model bridges.
 The rewrite has two Phase 7 prerequisites:
-1. **Abstract Java mixins over an abstract base — complete.** `registerJavaTrait` now admits `ACC_ABSTRACT` classes,
+1. **Abstract Java mixins over an abstract base - complete.** `registerJavaTrait` now admits `ACC_ABSTRACT` classes,
   retains declared abstract members on the generated interface, and omits them from the static helper and concrete
   method metadata until a later mixin supplies an implementation. A no-argument mixin constructor may call an
   argument-taking base constructor; that direct call is discarded because the generated composite invokes the real
   base constructor before trait initialization.
-2. **`@SideOnly` stripping on the Java path — complete.** `registerJavaTrait` checks both visible and invisible
+2. **`@SideOnly` stripping on the Java path - complete.** `registerJavaTrait` checks both visible and invisible
   annotations before collecting fields, signatures or methods. Opposite-side members are omitted; an excluded
   no-argument constructor produces an empty `$init$` so generated composites remain valid without executing its
   body, including when Forge stripped it before registration. Current-side members retain their generated behavior.
@@ -878,7 +878,7 @@ placeholder, rather than lost material data. Extra Utilities writes `mat` as wel
 UtilitiesInExcess's `extrautils:*` aliases; there is no legacy-conversion risk in the fix.

 - [x] Land the two Phase 7 Java-mixin prerequisites with generated Java-trait fixtures.
- [x] Provide the [Java illuminated microblock example](docs/api/MICROBLOCK_EXTENSIONS.md), including real Forge
+- [x] Provide the [Java illuminated microblock example](../api/MICROBLOCK_EXTENSIONS.md), including real Forge
  registration, all shape families, material/persistence/light contracts, server stripping and a headless retained
  client-body probe. The three example sources compile without Scala. Physical-client rendering remains a release gate.
 - [ ] Land the ProjectRed `LightMicroblock` Java rewrite with a fixture proving equivalent generated microblocks on
@@ -886,21 +886,21 @@ UtilitiesInExcess's `extrautils:*` aliases; there is no legacy-conversion risk i
 - [ ] Migrate Galacticraft to direct registration in gated compatibility code; exact-signature reflection is an interim option.
 - [ ] Fix the UtilitiesInExcess `mat`/`material` key mismatch and its `getIdMap()` use before it enters the pack.
 - [x] Add supported button-orientation mapping for Et Futurum as additive API, preserving the legacy arrays;
-  [guide and example](docs/api/BUTTON_ORIENTATIONS.md). Consumer migration/release/adoption remain pending.
+  [guide and example](../api/BUTTON_ORIENTATIONS.md). Consumer migration/release/adoption remain pending.
 - [x] Add the supported harvest-level setter needed by Iguana, preserving the legacy field name/type;
-  [guide and example](docs/api/SAW_STRENGTH.md). Iguana must finish changes before ForgeMicroblock post-init so its
+  [guide and example](../api/SAW_STRENGTH.md). Iguana must finish changes before ForgeMicroblock post-init so its
  cached maximum sees the final saw tiers. Consumer migration/release/adoption remain pending.
 - [x] Provide Schematica's registered-factory lookup without exposing the mutable map: `getPartFactory(String)`,
  with identity/missing-name checks, exact public reflection, a compiling example and the retained private field.
  This does not complete Schematica's consumer migration.
 - [x] Provide static Java client/server composite generation for Schematica and GuideNH, preserving exact reuse,
-  staged loading, input traversal/failure behavior and the old companion reflection path; [guide](docs/api/COMPOSITE_GENERATION.md).
+  staged loading, input traversal/failure behavior and the old companion reflection path; [guide](../api/COMPOSITE_GENERATION.md).
  Both consumers' release/adoption remain pending.
 - [x] Document and validate the existing Java microblock creation entry for GuideNH, including exact companion/static
  reflection, material trait callbacks, fresh-part/shape ownership and a compiling example. Keep physical-client
-  validation and public-setter versus private-field override behavior explicit; [guide](docs/api/MICROBLOCK_CREATION.md).
+  validation and public-setter versus private-field override behavior explicit; [guide](../api/MICROBLOCK_CREATION.md).
 - [x] Document and validate GuideNH's direct typed material query through existing `block()` / `meta()` accessors;
-  [guide](docs/api/MATERIAL_ACCESS.md). Consumer adoption and physical-client validation of the Java extension example remain open.
+  [guide](../api/MATERIAL_ACCESS.md). Consumer adoption and physical-client validation of the Java extension example remain open.
 - [ ] Patch those four consumers and record the released versions that no longer need the private shapes.
 - [ ] Track all legacy FMP dependencies in the adoption ledger, including trait helper/companion calls and reflection
  outside the cleanup table; verify the released jars actually selected for the target pack.
@@ -933,7 +933,7 @@ The repository uses Java-8-compatible JUnit Jupiter and the existing Forge integ
 are in the handoff. Minecraft 1.7.10 has no modern GameTest framework, so initialization-dependent tests use this
 Forge harness. The dedicated server is headless and does not establish client rendering correctness.

-### Layer 1 — Plain JVM characterization tests
+### Layer 1 - Plain JVM characterization tests

 Run fast tests through the normal Gradle `test` task, using real implementation classes and small fakes only at world, network, or rendering boundaries. Good targets include:

@@ -947,7 +947,7 @@ Run fast tests through the normal Gradle `test` task, using real implementation

 Finite input spaces such as sides, slot masks, and small recipe grids should be covered exhaustively. Larger combinations should use named regression cases plus deterministic property/fuzz tests with a recorded seed. Avoid tests that merely restate the implementation or assert interactions with a large graph of mocks.

-### Layer 2 — Golden compatibility fixtures
+### Layer 2 - Golden compatibility fixtures

 Store compact fixtures under test resources when behavior has a stable serialized or structural representation:

@@ -960,7 +960,7 @@ Store compact fixtures under test resources when behavior has a stable serialize

 Golden fixtures must be reviewed rather than regenerated automatically when they fail. Otherwise an accidental change can silently redefine the baseline.

-### Layer 3 — Real Forge integration tests
+### Layer 3 - Real Forge integration tests

 Use a dedicated test mod/source set launched in an actual Forge environment for behavior coupled to FML, the classloader, worlds, or networking. The harness should fail the Gradle task or process when an assertion fails. It should cover:

@@ -973,7 +973,7 @@ Use a dedicated test mod/source set launched in an actual Forge environment for

 Keep this harness narrow: a tiny test mod and deterministic scenarios are preferable to a general automation framework. Run server cases routinely; reserve the slower client cases for changes that touch rendering, client packets, or side-specific initialization.

-### Layer 4 — Irreducible manual and performance checks
+### Layer 4 - Irreducible manual and performance checks

 Some behavior remains poorly captured by assertions in a legacy client. Retain focused manual checks for visual correctness, selection boxes, particles, input interaction, resource reload, and third-party rendering compatibility. Screenshot comparisons can help, but GPU and renderer differences make them unsuitable as the only oracle.

@@ -1023,6 +1023,6 @@ Scala removal is gated by the compatibility evidence above, rather than by a rem

 ## Findings log

-The dated evidence log is archived in [docs/migration/HISTORY.md](docs/migration/HISTORY.md), including reference
+The dated evidence log is archived in [the history](HISTORY.md), including reference
 revisions, test results, ABI comparisons and resolved regressions. Add future per-target findings there.
-The [working handoff](JAVA_MIGRATION_HANDOFF.md) carries the current baseline and next target.
+The [working handoff](HANDOFF.md) carries the current baseline and next target.
@@ -8,7 +8,7 @@ rather than regenerated automatically, otherwise an accidental change silently r
 `gtnh-daily-678-consumers.txt` is the constant-pool scan of every mod jar in GTNH daily `2026-08-14+678`, listing
 every downstream reference into `codechicken/multipart` and `codechicken/microblock`. Regenerate with
 `tools/AbiScan.java` and diff against this file at every public-API phase; a member present here but absent from the
-port is a linkage break in a shipping mod. See `JAVA_MIGRATION_COMPATIBILITY.md` for the analysis.
+port is a linkage break in a shipping mod. See `docs/migration/COMPATIBILITY.md` for the analysis.

 ## Precompiled binary consumers

@@ -18,7 +18,7 @@ hide exactly the linkage failure the fixture exists to catch.

 `ReferenceScalaPartialOcclusion` was removed together with the `JPartialOcclusion$class` bridge once the inventory
 showed no downstream consumer of that helper. The trait helpers that do need this treatment are listed in
-`JAVA_MIGRATION_COMPATIBILITY.md`.
+`docs/migration/COMPATIBILITY.md`.

 ### `ReferenceScalaCuboidPart`