docs: keep the how-to guides to their steps

[TheMeinerLP]

Proposed changes

Brings the ten How-to guides in docs/how-to/ and the first-world tutorial in line with Diátaxis. A How-to
now holds the goal, the prerequisites, numbered steps with one code block per step, a check, and short
"See also" links. Explanation and reference content that sat inside the steps moved to the explanation and
reference pages (or was already there and is now linked). The tutorial follows one path with a visible
result per step.

Stacked on #101 (docs/correct-stale-facts), which is itself stacked on #99. Merge order: #99, #101, this PR.

Page by page:

• Tutorial (load-your-first-world-with-falco): one world layout (26.1+), pre-26.1 points to the How-to;
  imports moved to where they are used; shutdown hook fixed (see code corrections); the scheduler step has a
  checkable result; the "What you did" section moved to the loader-choice explanation.
• Add Falco to your build: Maven section now imports falco-bom and declares the modules; the rationale
  for the BOM and the 404 note moved to Versioning and Supported versions.
• Build Falco from source: credentials-and-401 explanation moved to Build setup; link to Build setup at the top.
• Load an Anvil world: signature table and default region limit moved to API surface; the map-provider
  explanation to the loader-choice page; TODO removed.
• Migrate a world from an older version: numbered steps; prerequisites clarified (backup applies to
  ON_DISK); rationale to World migration explanation; backup and floor details linked to Migration modes.
• Replace the version and unknown-entry policies: policy-resolution rules and the two-slot distinction
  linked to existing reference text; 4189 explained as a sample value.
• Compute light for a loaded world: borders and sky-light explanation moved to the light engine page;
  "one service serves every thread" moved to the concurrency page; the BlockLightSource example completed.
• Keep chunk light up to date automatically: type table moved to API surface; design, retraction,
  sky-light and batch explanations moved to the light engine page; measured figures already in Measured
  results and linked; "roughly 100 KB" removed (unsourced).
• Use FalcoInstance instead of InstanceContainer: lifecycle listener and read-only storage tables moved to
  API surface; events-versus-listener and shutdown rationale moved to the FalcoInstance explanation.
• Reproduce a published measurement: agreement criteria moved to "What a measurement here means"; the
  machine-record table stays as step 7; TODO removed.
• Run the JMH benchmark suite: size of the run to Benchmark catalogue; CI profiles and the shard rule to
  Benchmarks and demo; the rest is already present elsewhere and is linked.
• Build from source (also listed above) and Add to your build keep their check and troubleshooting sections.

Removed from → moved to / already in

"Moved" means the text was added to the target page in its style. "Already in" means the target page already
has the same content (quoted by location).

Removed from	Content	Moved to / already in
tutorial :35-36	two world layouts	one layout; pre-26.1 linked to how-to/load-an-anvil-world.md
tutorial :100-103	WARN level of the close summary	already in reference/logging.md ("Level is WARN when the error count is above zero")
tutorial :107-109	both switches are opt-in	moved to explanation/choosing-between-falco-and-the-built-in-loader.md ("Both switches are opt-in")
add-falco :57-58	why versions come from the BOM	moved to contributing/versioning-and-releases.md ("Why consumers take the version from the BOM")
add-falco :105	falco-bom not served below 1.0.0	moved to reference/supported-versions.md ("Artefact availability")
build-from-source :42-43	401 is the failure that occurs, not an outage	moved to contributing/build-setup.md ("Credentials and a 401 during resolution")
compute-light :35-38	one light service for all threads	moved to explanation/how-the-concurrency-design-works.md ("One light service serves every thread")
compute-light :46-91	sky light, border exchange, 3×3 reasoning	moved to explanation/how-the-light-engine-works.md ("Light across chunk borders")
keep-chunk :28-36	the five light types	moved to reference/api-surface-and-stability.md ("Light engine types")
keep-chunk :40-43	a change marks the 3×3	moved to explanation/how-the-light-engine-works.md ("A change marks the 3×3")
keep-chunk :45-51	a changed block costs a changed block	moved to same page ("A changed block costs a changed block")
keep-chunk :52-76	incremental vs full figures	already in reference/measured-results.md ("A replayed block change against lighting the chunks again")
keep-chunk :77-81	ratios reproduce, third digits do not	already in reference/measured-results.md ("An independent earlier run gave 1.96× / 6.40× / 3.95×")
keep-chunk :83-95	what is kept, its bound (128 cap)	moved to light engine page ("What is kept"); the 100 KB figure removed
keep-chunk :104-115	areas formed once per tick; nothing blocks	moved to light engine page ("When the scheduler computes"); caps already in explanation/scope-and-non-goals.md ("The kept light is capped")
keep-chunk :133-138	batches are covered	moved to light engine page ("Batches")
keep-chunk :155-181 incl. Mermaid	retraction	moved to light engine page ("Retracting light")
keep-chunk :183-203	sky-light updates	moved to light engine page ("Sky light updates")
load-an-anvil :86-91	constructor signatures	moved to reference/api-surface-and-stability.md ("Entry points and signatures")
load-an-anvil :93-95	map provider is reversible	moved to loader-choice explanation (same section)
load-an-anvil :103-106	default 64	moved to API surface ("Entry points and signatures", DEFAULT_OPEN_REGION_LIMIT)
migrate :17-18	IN_MEMORY leaves the world readable	already in explanation/how-world-migration-works.md ("The two halves", IN_MEMORY paragraph)
migrate :40-41	backup is moved, never removed	added as row "Removal" in reference/migration-modes.md (Backup)
migrate :51-53	fails to build without engine; below 1519 declined	already in reference/migration-modes.md ("Missing engine", "Floors")
migrate :54-55	renames without a rule stay air	moved to explanation/how-world-migration-works.md ("The rules, and where their numbers come from")
replace :30-31	default steps aside; two foreign providers throw	already in reference/replaceable-policies.md ("Resolution rules")
replace :44	the two slots are unrelated	already in reference/supported-versions.md ("Chunk data version floor", dataVersion row)
reproduce :10-12	cannot be reproduced exactly; environment unrecorded	already in reference/measured-results.md ("Measurement environment", "What follows from the empty rows")
reproduce :87-109	agreement criteria	moved to explanation/what-a-measurement-here-means.md ("What agreement would look like")
reproduce :107-109	ratios reproduce	already in reference/measured-results.md (same section and the ratio paragraph)
JMH :12-16	50 methods, 488 configurations, 300 cross product	moved to reference/benchmark-catalogue.md ("Size of the full run")
JMH :18-33	CI profiles and purpose	moved to contributing/benchmarks-and-demo.md ("The CI benchmark workflow")
JMH :35-41	CI figures are not the published machine	already in explanation/what-a-measurement-here-means.md (1.35× against 1.13×)
JMH :43-45	a shard is a whole class	moved to contributing/benchmarks-and-demo.md (same section)
JMH :98-100	-prof gc answers allocation claims	already in explanation/what-the-benchmarks-establish.md (-prof gc paragraph)
JMH :103-117	why build does not run them	already in contributing/benchmarks-and-demo.md (full run, compileJmhJava)
use-falcoinstance :18-23	immutable builder, constructors	reference/api-surface-and-stability.md ("Entry points and signatures")
use-falcoinstance :39-42	owns loader, saves on shutdown	moved to explanation/why-falco-instance-exists.md ("Owning the loader and saving on shutdown")
use-falcoinstance :47-49	did not work before 1.0.0	already in explanation/choosing-between-falcoinstance-and-instancecontainer.md ("Before 1.0.0 this combination did not work at all")
use-falcoinstance :63-68	light engine on the instance, compileOnly	moved to explanation/why-falco-instance-exists.md ("The light engine on the instance")
use-falcoinstance :70-87	events versus listener	moved to same page ("Events and the chunk lifecycle listener")
use-falcoinstance :101-121	full listener	moved to reference/api-surface-and-stability.md ("Chunk lifecycle listener")
use-falcoinstance :148-158	view settings, construction order	already in explanation/why-falco-instance-exists.md ("Shared instances", table); order paragraph added
use-falcoinstance :161-174	read-only storage	moved to reference/api-surface-and-stability.md ("Read-only section access")

Code corrections

• Tutorial: new Thread(loader::close) did not compile, because FalcoAnvilLoader#close() throws
  IOException. Replaced with a lambda that catches it; java.io.IOException added to the imports.
• Tutorial: the scheduler imports were shown as a loose fragment; they are now listed for the top of the file.
• Migrate: worldRoot, dimension, ChunkMigrationMode and Key were undefined or unimported; defined and imported.
• Replace policies: dimension and Path defined and imported; the two user-supplied policies marked as yours.
• Compute light: Chunk imported; instance and chunk coordinates marked as yours; the BlockLightSource example
  now has its imports (net.onelitefeather.falco.light.BlockFace, BlockLightSource) and defines LAMP and STONE,
  which were undefined.
• Keep chunk light: imports added; instance and opacityTables marked as yours.
• Use FalcoInstance: imports added to every snippet; the undefined log became logger, manager is defined,
  and the listener example no longer refers to an undefined collection.
• Build from source, load Anvil, JMH, reproduce: method names and signatures were checked against the code
  (FalcoAnvilLoader constructors and close(), FalcoInstance.builder and registerAndShutdownWith,
  ChunkLightService, ChunkLightState#update, LightPropagator#propagate, SectionOpacity.of,
  FalcoSharedInstance constructor, ChunkLifecycleListener defaults); no other mismatch was found.
• Replace policies: the literal 4189 is not a constant in the code (it appears only as a sample value in the
  demo and benchmark sources), so the example says so instead of naming a constant.

Removed TODO(maintainer) comments

These were HTML comments in the published text of the three pages below. Their content is listed here verbatim
so that it can become an issue.

docs/how-to/load-an-anvil-world.md:

TODO(maintainer): this section previously documented an Aves integration built on a
     `ChunkLoaderFactory` functional interface and a four-argument
     `AbstractMapProvider#registerInstance` overload. Neither exists. `ChunkLoaderFactory` appears in
     no .java file in this repository and in no commit of its history (`git log --all -S`), Falco
     declares no dependency on Aves in any build file, and `net.theevilreaper.aves.map.provider
     .AbstractMapProvider` at Aves 1.16.0 declares only the two- and three-argument overloads. The
     section below states what is true today. Restore the factory prose once the interface is
     actually shipped, on either side.

docs/how-to/reproduce-a-published-measurement.md:

TODO(maintainer): fill the same table in for the published runs, from the machine they came
     from, and commit the results.json files. Leave a field as TBD rather than guessing — a wrong
     value is worse than a missing one. The only facts currently recorded anywhere are: 16 cores,
     machine not idle, JMH 1.37, Java 25 toolchain, Minestom 2026.06.20-26.1.2.

docs/how-to/keep-chunk-light-up-to-date-automatically.md:

TODO(maintainer): the "roughly 100 KB per chunk and kind of light" figure has no committed
     source — no -prof gc output, no heap dump, no test that asserts it. The 128-chunk cap is a
     constant and is checkable; the per-entry size is not. Either attach the measurement or derive
     the number from the field layout of ChunkLightState in the javadoc and cite that. It is quoted
     twice on this page and both places inherit whatever is decided.

Not touched in this PR (outside the How-to pages and the tutorial, so not moved or edited): the other
TODO(maintainer) comments in explanation and reference pages, and the "roughly 100 KB" / "about 100 KB" wording
in reference/measured-results.md and explanation/what-a-measurement-here-means.md, which may need the same decision.

Types of changes

• Documentation Update

Checklist

• The title of this pull request is a Conventional Commit.
• I have added necessary documentation (if appropriate)

https://claude.ai/code/session_01Q6AxU7jRLmNPHdwg2GpasT