docs: limits of the native build, garbage collector row, migration steps

docs/modules/ROOT/pages/installation.adoc

@@ -167,6 +167,18 @@ export ARCADEDB_NATIVE_ISOLATE_ARGS="-XX:MaxRAM=4g"                 # a memory s
 
 When one of these three is present, the package adds no default. Do not use `-XX:MaxRAMPercentage`. The native image does not accept it, and the isolate then fails to start with `graal_create_isolate failed (rc=22)`. The same variable also takes the engine's `-D` settings: see xref:how-to/logs.adoc[Where the logs go]. For what a native image build supports, see xref:arcadedb::how-to/operations/native-image.adoc[Native image] in the main ArcadeDB docs.
 
+[[native-limits]]
+=== Limits of the native build
+
+What the native package cannot do, or does differently from `{jvm-pkg-name}`. Read this before you pick it for a production service.
+
+* *Serial garbage collector.* GraalVM Community Edition offers one garbage collector for native images, the serial one (the G1 collector is part of Oracle GraalVM only). A collection stops all threads, and its pause grows with the amount of live data. For a heavy, long-running load, a large heap or many busy threads, use `{jvm-pkg-name}`.
+* *Heap limit of 50% by default.* The package sets `-XX:MaximumHeapSizePercent=50`, so the process holds at most half of the memory it can see. See <<native-heap>> to change it.
+* *No Java objects, no JVM options.* `get_java_database`, `get_java_document` and the other `get_java_*` calls raise `NotOnNativeYet`. `start_jvm`, `jvm_kwargs` and the flags in <<jvm-options>> do not exist.
+* *No console log on Windows by default.* The log goes to the file only. See xref:how-to/logs.adoc[Where the logs go] for the reason and for `ARCADEDB_LOG_CONSOLE`.
+* *Engine modules left out.* The gRPC and MongoDB wire protocols, Raft HA, Gremlin and the polyglot languages (JavaScript, Python as a query language) are not in the image. See <<what-is-included>>.
+* *Platforms.* Intel Macs, Alpine Linux (musl) and Windows on ARM have no wheel. See <<requirements>>.
+
 == Next steps
 
 * xref:quickstart.adoc[Quickstart]

docs/modules/ROOT/pages/which-package.adoc

@@ -62,6 +62,10 @@ The API is the same. The runtime is not. These are the differences you can plan
 | Small footprint.
 | Larger. The JVM keeps a heap, and each Python process starts its own JVM.
 
+| Garbage collector
+| The serial collector of GraalVM Community Edition. A collection stops all threads, and the pause grows with the live data. The heap limit is 50% of the memory by default (xref:installation.adoc#native-heap[Heap size]).
+| The JVM's own collectors, G1 by default on a server-class machine. You choose them and the heap with `jvm_kwargs` (xref:installation.adoc#jvm-options[JVM options]).
+
 | Throughput on long loads
 | No JIT warm-up. Speed over a long run depends on the workload.
 | The JIT compiler makes long-running loads faster over time.
@@ -133,6 +137,13 @@ The packages had other names until 26.10.x. Search results and old tutorials may
 | The same build, now with the import name `{import-name}`. The old preview versions were 26.10.x pre-releases.
 |===
 
+[[migrate]]
+=== Migrate from the old names
+
+. Remove the old package: `pip uninstall arcadedb-embedded arcadedb-embedded-native`.
+. Install the new one: `pip install {jvm-pkg-name}` if you used `arcadedb-embedded`, or `pip install {native-pkg-name}` if you used `arcadedb-embedded-native`. Add `--pre` while the transition note above applies.
+. Change the import: `import arcadedb_embedded` and `import arcadedb_native` both become `import {import-name}`. The builds are the same as in the table above, so the rest of your code stays.
+
 The old packages will get a deprecation shim that points to the new names. Releases of the new layout start with 26.11.1. The 26.10.x wheels were built in a separate repository of the humemai organisation.
 
 [[drivers]]