docs: lead with the package choice, drop arcadedb-native and unmeasured start-up numbers, state what happens to the old names

README.md

@@ -7,7 +7,7 @@
 [![Tests native](https://github.com/ArcadeData/arcadedb-python/actions/workflows/test-native.yml/badge.svg)](https://github.com/ArcadeData/arcadedb-python/actions/workflows/test-native.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/ArcadeData/arcadedb-python/blob/main/LICENSE)
 
-Python bindings for [ArcadeDB](https://arcadedb.com), the multi-model database (graph, document, key/value, vector and time series, queried with SQL or openCypher). The engine runs inside your Python process, with no server and no network hop. This repository builds two packages, and both import as `arcadedb`. `arcadedb-jvm` has a sibling, `arcadedb`, the native build: pick `arcadedb` for scripts, notebooks, tests, CLIs, serverless functions and agents, and `arcadedb-jvm` for heavy, long-running loads. Status: beta.
+Python bindings for [ArcadeDB](https://arcadedb.com), the multi-model database (graph, document, key/value, vector and time series, queried with SQL or openCypher). The engine runs inside your Python process, with no server and no network hop. This repository builds two packages, and both import as `arcadedb`: `arcadedb` (the native build, the default) for scripts, notebooks, tests, CLIs, serverless functions and agents, and `arcadedb-jvm` (the JVM build) for heavy, long-running loads. Status: beta.
 
 | Package | Engine | Pick it for |
 |---|---|---|
@@ -24,10 +24,10 @@ pip install arcadedb-jvm   # JVM, for heavy long-running loads (or: uv add arcad
 ```
 
 <!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
-> Transition note: the first release of this layout is 26.11.1. Until `arcadedb` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Install it with `pip install --pre arcadedb` (or `uv add --prerelease allow arcadedb`).
+> Transition note: the first release of this layout is 26.11.1. Until `arcadedb` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Install it with `pip install --pre arcadedb` (or `uv add --prerelease allow arcadedb`). A plain `pip install arcadedb` finds only the 0.0.1 placeholder, which installs the old package. The same holds for `arcadedb-jvm` until its 26.11.1 is released.
 
 <!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
-> Old names: `arcadedb-jvm` was formerly `arcadedb-embedded`, and `arcadedb` was formerly `arcadedb-embedded-native`. The old packages will get a deprecation shim.
+> Old names: `arcadedb-jvm` was formerly `arcadedb-embedded`, and `arcadedb` was formerly `arcadedb-embedded-native` (archived on PyPI). A last `arcadedb-embedded` release will be a deprecation shim that installs `arcadedb`, the native build.
 
 - Python 3.11 to 3.14. CI builds and tests all four versions on every platform below for `main`, every night and each release. A pull request runs a smaller selection.
 - Linux x86_64 and ARM64, macOS on Apple Silicon, Windows x86_64, for both packages. The Windows wheel of `arcadedb` is the newest.
@@ -74,18 +74,17 @@ For several processes, other languages, HA or replication, run the official Dock
 |---|---|---|
 | [`arcadedb`](https://pypi.org/project/arcadedb/) | The native build: the engine compiled by GraalVM Community Edition, no JVM, no JPype. The default for embedded use | First release of this layout: 26.11.1. It may first appear as `26.11.1.devN` pre-releases |
 | [`arcadedb-jvm`](https://pypi.org/project/arcadedb-jvm/) | The JVM build: the Java engine on a bundled JVM, through JPype. The package this README described before the two-package layout | First release from this repository: 26.11.1 |
-| `arcadedb-native` | An alias of `arcadedb`: same version, it only installs `arcadedb` | Planned |
 
 <!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
-Formerly `arcadedb-embedded` (now `arcadedb-jvm`, the same build) and formerly `arcadedb-embedded-native` (now `arcadedb`). They imported as `arcadedb_embedded` and `arcadedb_native`, and they are deprecated.
+Formerly `arcadedb-embedded` (now `arcadedb-jvm`, the same build) and formerly `arcadedb-embedded-native` (now `arcadedb`). They imported as `arcadedb_embedded` and `arcadedb_native`, and they are deprecated: `arcadedb-embedded-native` is archived, and `arcadedb-embedded` will get a last release that installs `arcadedb`.
 
 Releases from this repository start with 26.11.1. The 26.10.x wheels were built and published from [humemai/arcadedb-embedded-python](https://github.com/humemai/arcadedb-embedded-python). <!-- allow-old-name -->
 
 ## Documentation
 
 - Here: [`docs/`](https://github.com/ArcadeData/arcadedb-python/tree/main/docs/modules/ROOT/pages) is an Antora component (AsciiDoc) with Installation, [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc), Quickstart, Databases and queries, and Concurrency, processes and crashes. It covers only what is specific to the Python bindings.
 - The component is not published on docs.arcadedb.com yet; adding it as a content source is open in [ArcadeData/arcadedb-docs#505](https://github.com/ArcadeData/arcadedb-docs/pull/505).
-- The guide, API reference and example walkthroughs for the published package are still at [docs.humem.ai/arcadedb](https://docs.humem.ai/arcadedb/latest/) until those pages are ported here ([#19](https://github.com/ArcadeData/arcadedb-python/issues/19)).
+- The older guide, API reference and example walkthroughs are at [docs.humem.ai/arcadedb](https://docs.humem.ai/arcadedb/latest/). They describe the previous packages and use the import name `arcadedb_embedded`; read it as `arcadedb`. They stay until those pages are ported here ([#19](https://github.com/ArcadeData/arcadedb-python/issues/19)). <!-- allow-old-name -->
 - ArcadeDB itself (SQL, openCypher, schema, server): [docs.arcadedb.com](https://docs.arcadedb.com). It is not repeated here.
 
 ## Examples

docs/modules/ROOT/pages/index.adoc

@@ -6,20 +6,25 @@
 
 These packages run the ArcadeDB engine inside your Python process, with no network hop and no server to start. Two packages exist, and both use the import name `{import-name}`:
 
-[cols="1,3,3"]
+[cols="1,3,3,2"]
 |===
-| Package | Engine | Pick it for
+| Package | Engine | Pick it for | Install
 
 | `{native-pkg-name}` (the default)
 | Native: the engine compiled by GraalVM Community Edition, loaded with `ctypes`. No JVM, no JPype.
 | Scripts, notebooks, tests, CLIs, serverless functions and agents.
+| `pip install {native-pkg-name}`
 
 | `{jvm-pkg-name}`
 | JVM: the Java engine in your process through https://jpype.readthedocs.io/[JPype], with a bundled Java 25 runtime.
 | Heavy, long-running loads, and the Java-object APIs.
+| `pip install {jvm-pkg-name}`
 |===
 
-Not sure which one? Read xref:which-package.adoc[Which package?]. Install one of them, not both.
+Not sure which one? Take `{native-pkg-name}`, and read xref:which-package.adoc[Which package?] to decide for sure. Install one of them, not both.
+
+// REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name
+NOTE: *Transition note.* The first release of this layout is 26.11.1, and `{native-pkg-name}` may first appear as pre-releases, `26.11.1.devN`. Until a final 26.11.1 is on PyPI, install it with `pip install --pre {native-pkg-name}`: a plain `pip install` finds only the 0.0.1 placeholder, which installs the old package. See xref:installation.adoc[Installation].
 
 ArcadeDB is a multi-model database: graph, document, key/value, vector and time series data live in one database, and you query it with SQL or openCypher. The bindings expose the two calls you need for that, `db.command(...)` and `db.query(...)`.
 
@@ -75,7 +80,7 @@ The two meet in one case. The bindings bundle an optional HTTP server. It is off
 [[jvm-vs-native]]
 == Native build or JVM build
 
-Both packages give you the same engine and the same API. The table in xref:which-package.adoc[Which package?] lists what differs: start-up time, memory, platforms, and the APIs that exist only on the JVM build (`get_java_database`, `jvm_kwargs`, `start_jvm`). The pages in this component apply to both packages. Parts that apply to one only say so.
+Both packages give you the same engine and the same API. xref:which-package.adoc[Which package?] lists what differs. The pages in this component apply to both packages, and a part that applies to one says so.
 
 Check which one you have with `python -c "import arcadedb; print(arcadedb.__backend__)"`. It prints `native` or `jvm`.
 

docs/modules/ROOT/pages/installation.adoc

@@ -6,7 +6,7 @@
 
 == Install
 
-Pick one of the two packages. Both import as `{import-name}`.
+Pick one of the two packages. Both import as `{import-name}`. If you are not sure, take `{native-pkg-name}`.
 
 [cols="1,2,2"]
 |===
@@ -26,10 +26,10 @@ Pick one of the two packages. Both import as `{import-name}`.
 Install one of them, not both. If both are installed, `import arcadedb` raises an `ImportError` that names both packages. See xref:which-package.adoc[Which package?] for the comparison, and for how to switch.
 
 // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name
-NOTE: *Transition note.* The first release of this layout is 26.11.1. Until `{native-pkg-name}` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Install it with `pip install --pre {native-pkg-name}` or `uv add --prerelease allow {native-pkg-name}`.
+NOTE: *Transition note.* The first release of this layout is 26.11.1. Until `{native-pkg-name}` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Install it with `pip install --pre {native-pkg-name}` or `uv add --prerelease allow {native-pkg-name}`. A plain `pip install {native-pkg-name}` finds only the 0.0.1 placeholder, which installs the old package. The same holds for `{jvm-pkg-name}` until its 26.11.1 is released.
 
 // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name
-NOTE: *Old names.* The JVM package was formerly `arcadedb-embedded`. It is now `{jvm-pkg-name}`, the same build. The native package was formerly `arcadedb-embedded-native`. It is now `{native-pkg-name}`. See xref:which-package.adoc#old-names[Old names].
+NOTE: *Old names.* The JVM package was formerly `arcadedb-embedded`. It is now `{jvm-pkg-name}`, the same build. The native package was formerly `arcadedb-embedded-native`. It is now `{native-pkg-name}`, and the old project is archived. A last `arcadedb-embedded` release will install `{native-pkg-name}`, not `{jvm-pkg-name}`. See xref:which-package.adoc#old-names[Old names].
 
 The JVM package is self-contained. It carries a Java 25 runtime for its platform, so you do not install Java. Its only Python dependency is `JPype1` 1.5.0 or later (the Java-Python bridge), which pip installs for you. The native package needs no Java and no JPype. Optional extras install the columnar helpers of the native package: `[numpy]`, `[arrow]`, `[pandas]` and `[polars]`.
 

docs/modules/ROOT/pages/quickstart.adoc

@@ -18,7 +18,10 @@ This page builds a small database from scratch. You need one of the two packages
 | Heavy, long-running loads, or the Java-object APIs.
 |===
 
-See xref:which-package.adoc[Which package?] if you are not sure. The scripts on this page ran against the published `{jvm-pkg-name}` wheel, and the output shown is what it printed. The code is the same for both packages. The wording of an error message can differ on `{native-pkg-name}`.
+See xref:which-package.adoc[Which package?] if you are not sure. If you are not sure, take `{native-pkg-name}`. Until a final 26.11.1 is on PyPI, add `--pre` to the install line of `{native-pkg-name}` (see the transition note in xref:installation.adoc[Installation]).
+
+// REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name
+The scripts on this page ran against the JVM build, version 26.10.2.post1 (formerly `arcadedb-embedded`). The output shown is what it printed. The code is the same for both packages. The wording of an error message can differ on `{native-pkg-name}`.
 
 == Embedded mode
 

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

@@ -9,7 +9,7 @@ Two packages give you the ArcadeDB engine inside your Python process. Both use t
 
 | `{native-pkg-name}` (the default)
 | The native build. The engine is compiled by GraalVM Community Edition into a shared library, which Python loads with `ctypes`. No JVM, no JPype, no bundled Java runtime.
-| Embedded use in scripts, notebooks, tests, CLIs, serverless functions and agents. It starts in milliseconds and holds little memory.
+| Embedded use in scripts, notebooks, tests, CLIs, serverless functions and agents. It starts fast and holds little memory, because there is no JVM.
 
 | `{jvm-pkg-name}`
 | The JVM build. The Java engine runs in your process through https://jpype.readthedocs.io/[JPype], on a bundled Java 25 runtime.
@@ -25,9 +25,7 @@ pip install {jvm-pkg-name}        # JVM, for heavy long-running loads
 If you are not sure, install `{native-pkg-name}`. You can switch later: your code does not change (see <<switching>>).
 
 // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name
-NOTE: *Transition note.* The first release of this layout is 26.11.1. Until the native build passes its readiness bar, `{native-pkg-name}` may appear only as pre-releases, `26.11.1.devN`. Then you install it with `pip install --pre {native-pkg-name}` (or `uv add --prerelease allow {native-pkg-name}`). The readiness bar is listed in xref:development/release.adoc[Release].
-
-A third name is planned: `arcadedb-native`. It is an alias of `{native-pkg-name}`, with the same version, and it only installs `{native-pkg-name}`. It is not published yet.
+NOTE: *Transition note.* The first release of this layout is 26.11.1. Until the native build passes its readiness bar, `{native-pkg-name}` may appear only as pre-releases, `26.11.1.devN`. Then you install it with `pip install --pre {native-pkg-name}` (or `uv add --prerelease allow {native-pkg-name}`). A plain `pip install {native-pkg-name}` finds only the 0.0.1 placeholder, which installs the old package (see <<old-names>>), until a final 26.11.1 exists. The same holds for `{jvm-pkg-name}` until its 26.11.1 is released. The readiness bar is listed in xref:development/release.adoc[Release].
 
 [[which-one-do-i-have]]
 == Check which one you have
@@ -55,8 +53,8 @@ The API is the same. The runtime is not. These are the differences you can plan
 | | `{native-pkg-name}` (native) | `{jvm-pkg-name}` (JVM)
 
 | Start-up
-| Milliseconds. There is no JVM to start.
-| About one second or more, to start the JVM.
+| Fast. There is no JVM to start.
+| Slower. Every Python process starts a JVM first.
 
 | Memory
 | Small footprint.
@@ -126,11 +124,11 @@ The packages had other names until 26.10.x. Search results and old tutorials may
 
 | `{jvm-pkg-name}`
 | Formerly `arcadedb-embedded`, imported as `arcadedb_embedded`
-| The same build. Nothing changes silently in the runtime. The import name is now `{import-name}`.
+| The same JVM build, with the import name `{import-name}`. The last release of the project formerly `arcadedb-embedded` (26.11.1) will be a deprecation shim that installs `{native-pkg-name}`, the native build, and warns. If you need the JVM build, install `{jvm-pkg-name}` yourself.
 
 | `{native-pkg-name}`
 | Formerly `arcadedb-embedded-native`, imported as `arcadedb_native`
-| The same build, now with the import name `{import-name}`. The old preview versions were 26.10.x pre-releases.
+| The same build, now with the import name `{import-name}`. The old preview versions were 26.10.x pre-releases. The old project is archived on PyPI: no new releases and no shim.
 |===
 
 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.

native/wheel/README.md

@@ -16,7 +16,7 @@ pip install arcadedb       # or: uv add arcadedb
 Optional extras for the columnar helpers: `[numpy]`, `[arrow]`, `[pandas]`, `[polars]`.
 
 <!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
-Old names: this package was formerly `arcadedb-embedded-native`, imported as `arcadedb_native`. The old package will get a deprecation shim that points here.
+Old names: this package was formerly `arcadedb-embedded-native`, imported as `arcadedb_native`. The old project is archived on PyPI: it gets no new releases and no shim. A last release of the JVM project `arcadedb-embedded` will install this package.
 
 If `arcadedb-jvm` is installed in the same environment, `import arcadedb` raises an `ImportError` that names both packages. Run `pip uninstall arcadedb arcadedb-jvm`, then install the one you want.