diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md
new file mode 100644
index 0000000..8776f8f
--- /dev/null
+++ b/docs/agent-handoff.md
@@ -0,0 +1,67 @@
+# Agent Handoff
+
+## Current State
+
+The repository now contains a private NeoForge `21.1.228` / Minecraft `1.21.1` porting scaffold for Explosion Overhaul.
+
+The Gitea runner has been used for:
+
+- decompiling the upstream Forge `0.2.3.0` jar,
+- publishing the decompiled output to `runner/decompiled-upstream`,
+- running repeated NeoForge builds on `main`.
+
+## Changes Made
+
+- Added `.gitea/workflows/decompile.yml` to decompile the upstream jar on the runner.
+- Added `.gitea/workflows/build.yml` to build with Java 21 on the runner.
+- Added NeoForge ModDevGradle scaffold files.
+- Imported decompiled Java sources under `src/main/java`.
+- Imported upstream assets and resources under `src/main/resources`.
+- Added `src/main/templates/META-INF/neoforge.mods.toml`.
+- Applied first mechanical package migration from Forge packages to NeoForge packages.
+- Repaired CFR control-flow artifacts in:
+  - `AsyncCraterManager`
+  - `BlockIndexManager`
+- Fixed runner setup issues:
+  - executable `gradlew`
+  - tracked `gradle-wrapper.jar`
+  - CurseMaven exclusive dependency lookup
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| `git diff --check` | PASS before last committed source fixes |
+| Gitea decompile workflow | PASS |
+| Gitea build workflow | FAIL, now reaches Java API migration errors |
+
+Latest checked build:
+
+```text
+Run ID: 165
+Job ID: 166
+Conclusion: failure
+```
+
+## Current Build Blockers
+
+The remaining failures are real Forge-to-NeoForge/API-porting work, not runner setup:
+
+- `RenderGuiOverlayEvent` no longer exists in the same form.
+- `NetworkEvent.Context`, `NetworkRegistry`, and `SimpleChannel` need migration to NeoForge's 1.21 networking API.
+- `ConfigScreenHandler` needs migration to the NeoForge config screen registration API.
+- `DistExecutor` imports need replacement/removal for NeoForge 1.21.
+- `@Mod.EventBusSubscriber` needs migration to NeoForge's event subscriber annotation.
+- `ForgeRegistries` / `RegistryObject` usage needs migration to the modern NeoForge registry holders.
+
+## Next Steps
+
+1. Migrate registry classes first (`ModSounds`, `ModBlocks`, `ModItems`, `ModParticles`, `ModBlockEntities`, creative tabs).
+2. Migrate packet registration and all packet handlers away from Forge `SimpleChannel` / `NetworkEvent.Context`.
+3. Replace GUI overlay events and config screen registration.
+4. Re-run the Gitea build after each API family rather than attempting all files at once.
+
+## Risks
+
+- This is decompiled, All Rights Reserved upstream code. Keep the repo private and do not publish builds without permission.
+- The port is large: after compile succeeds, runtime testing in a real NeoForge client will still be required for explosions, scan UI, audio effects, shaders, and mixins.