diff --git a/DEVNET.md b/DEVNET.md
new file mode 100644
index 0000000..1165e9e
--- /dev/null
+++ b/DEVNET.md
@@ -0,0 +1,51 @@
+# aere-devnet: AERE on your machine in one command
+
+The same binary the nine mainnet validators run (the Besu fork with the AERE base-fee floor, the
+post-quantum message layers and the post-quantum precompiles), started as a **local
+single-validator chain**: chain id **28002**, one block every 500 ms, ten funded accounts, every read
+AND debug API open (`DEBUG`, `TRACE`, `TXPOOL`). Nothing here connects to mainnet 2800: different
+chain id, different genesis, no peer-to-peer outside the container.
+
+```
+docker run --rm -p 8545:8545 -p 8546:8546 git.aere.network/aere-network/devnet:latest
+```
+
+Then point Hardhat, Foundry, MetaMask or `cast` at `http://127.0.0.1:8545` (chain id 28002).
+`web3_clientVersion` returns the fleet's own version stamp, so you can see exactly which build you run.
+
+## Accounts
+
+The ten accounts are derived from the **public Hardhat test mnemonic** (`test test test test test
+test test test test test test junk`, paths `m/44'/60'/0'/0/{0..9}`), 10,000 AERE each. Account #0 is
+also the validator. Anyone can derive these keys: **never use them on a real network.**
+
+## What is real and what is not
+
+- Real: the execution engine, the AERE base-fee floor fork, the post-quantum precompiles at
+  `0x0AE1..0x0AE6` from genesis, `debug_traceTransaction` / `trace_*` on every block, 500 ms blocks.
+- Not real: consensus security. One validator, no Falcon registry, no post-quantum anchor, no
+  post-quantum message enforcement (those need a registry of Falcon keys; the public testnet 28001
+  has all of that, this image deliberately does not). Empty blocks are still produced every 500 ms,
+  so a long-running devnet grows its `/data` volume; use `--rm` or mount a volume you can delete.
+
+## Options
+
+- `-v aere-devnet:/data` persists the chain between runs.
+- `-e AERE_DEVNET_LOG=DEBUG` for verbose node logs.
+- Extra Besu flags can be appended after the image name.
+
+## How the image is built
+
+From the fleet image's `/opt/besu` directory, copied unchanged onto a jlinked JRE 25 on Ubuntu 24.04
+(about 300 MB). Every layer stays under 100 MB because the registry sits behind an edge that refuses
+larger uploads; the build script measures the layers and refuses to publish otherwise. Before
+publishing, the build starts the image, checks that blocks advance, sends a real transfer, and runs
+`trace_transaction`, `debug_traceTransaction`, `trace_block` and a call to the Falcon precompile on it.
+
+## Trace on the public read node
+
+`rpc2.aere.network` also answers the read-only debug and trace methods (`debug_traceTransaction`,
+`debug_traceBlockByNumber`, `debug_traceBlockByHash`, `debug_traceCall`, `debug_getRaw*`,
+`trace_transaction`, `trace_block`, `trace_call`, `trace_replayBlockTransactions`). It is a full node
+with a 512-block state window, so traces are available for recent blocks; write-capable methods of
+those namespaces are refused at the edge.