docs: 'Which package for which mode' page; link the main docs instead of re-explaining

docs/antora.yml

@@ -13,5 +13,13 @@ asciidoc:
     import-stmt: import arcadedb_embedded as arcadedb
     native-pkg-name: arcadedb-embedded-native
     native-import-name: arcadedb_native
+    # Other names a reader meets on PyPI (the pages that compare packages use these).
+    short-pkg-name: arcadedb
+    short-native-pkg-name: arcadedb-native
+    jvm-pkg-name: arcadedb-jvm
+    driver-pkg-name: arcadedb-driver
+    grpc-driver-pkg-name: arcadedb-driver-grpc
+    community-driver-pkg-name: arcadedb-python
+    community-repo-url: https://github.com/stevereiner/arcadedb-python
     repo-url: https://github.com/ArcadeData/arcadedb-python
     pypi-url: https://pypi.org/project/arcadedb-embedded/

docs/modules/ROOT/nav.adoc

@@ -1,5 +1,6 @@
 * xref:index.adoc[ArcadeDB Python]
 * xref:installation.adoc[Installation]
+* xref:packages.adoc[Which package for which mode]
 * xref:quickstart.adoc[Quickstart]
 * How-to
 ** xref:how-to/databases-and-queries.adoc[Databases and queries]

docs/modules/ROOT/pages/how-to/databases-and-queries.adoc

@@ -204,7 +204,7 @@ total: 2
 
 === Parameters
 
-Bind values as parameters instead of pasting them into the statement text. A pasted value can change the statement (SQL injection), and a quote in a name breaks it. ArcadeDB also caches parsed statements by their text, so every distinct pasted value is parsed again. Identifiers such as type and property names cannot be bound and belong in the text.
+Bind values as parameters instead of pasting them into the statement text. Identifiers such as type and property names cannot be bound and belong in the text.
 
 * Positional: one `?` per value, from the extra arguments (`db.query("sql", q, "Alice", 25)`) or from one list or tuple (`db.query("sql", q, ["Alice", 25])`).
 * Named: `:name` in the statement and a dict as the one extra argument. A named parameter can hold a collection, as in `age IN :ages`.
@@ -219,15 +219,17 @@ Bind values as parameters instead of pasting them into the statement text. A pas
 
 === Pagination
 
-For a large type, page by `@rid` instead of `SKIP`. Each page is `WHERE @rid > ? LIMIT ?`, and the cursor is the `@rid` of the last row of the previous page. Start with `"#-1:-1"`. The script above shows the loop with a page size of one so that two short pages print.
+Page a large type by `@rid` instead of `SKIP`: each page is `WHERE @rid > ? LIMIT ?`, and the cursor is the `@rid` of the last row of the previous page. Start with `"#-1:-1"`. The script above runs the loop with a page size of one so that two short pages print.
 
 === SQLScript
 
-`db.command("sqlscript", script)` runs several statements in one call. Without an explicit `RETURN`, the result set holds the last executed statement, DDL such as `CREATE` and `ALTER` included. That is why the script above reports the `ALTER TYPE` statement.
+`db.command("sqlscript", script)` runs several statements in one call, and the result set holds the last executed statement, which is why the script above reports the `ALTER TYPE` statement. The script syntax is in the xref:arcadedb::reference/sql/sql-script.adoc[SQLScript reference].
 
 === openCypher
 
-The same two calls run openCypher: pass `"opencypher"` as the language. The script creates an edge with a `CREATE` pattern and reads it back with `MATCH`.
+The same two calls run openCypher: pass `"opencypher"` as the language. The script creates an edge with a `CREATE` pattern and reads it back with `MATCH`. The language is documented in the xref:arcadedb::reference/cypher/chapter.adoc[openCypher reference].
+
+NOTE: ArcadeDB SQL has no JOINs, so SQLAlchemy and other ORMs, and tools that generate `JOIN` queries, do not work with these two calls. Write the statements yourself, following links as in xref:arcadedb::reference/sql/sql-introduction.adoc#no-joins[No JOINs], or use openCypher for relationships.
 
 == Next steps
 

docs/modules/ROOT/pages/index.adoc

@@ -57,6 +57,7 @@ Choose the embedded bindings for a single script, a notebook, or an application
 
 The two meet in one case. The bindings bundle an optional HTTP server with the Studio web UI. It is off until you call `create_server()`. The process that owns the database keeps direct access, and other processes connect over HTTP. That server lives and dies with your Python process. For a database that must outlive any one client, or for HA, replication and TLS, run the regular xref:arcadedb::index.adoc[ArcadeDB server] instead.
 
+[[jvm-vs-native]]
 == JVM build or native build
 
 Two packages ship for now. Both give you the same engine and the same API.

docs/modules/ROOT/pages/packages.adoc

@@ -0,0 +1,64 @@
+= Which package for which mode
+:description: Pick between the embedded JVM package, the embedded native package, the official server drivers and the community driver of the same name.
+
+Several PyPI packages mention ArcadeDB, and two of them look alike. This page says which is which and which one to install for your process.
+
+== The short answer
+
+* One Python process owns the database and you want the simplest setup: install `{pkg-name}`. It runs the engine on the JVM, inside your process, and bundles its own Java runtime.
+* A short-lived process, or one where memory and start-up time matter: install `{native-pkg-name}`. It runs the engine as a GraalVM native image. It is a preview.
+* Several processes, or several services, share one database: run an ArcadeDB server and talk to it with a driver (see <<drivers>>).
+
+== Rule of thumb
+
+[cols="2,3"]
+|===
+| Your process | Use
+
+| Short-lived and footprint-sensitive: a CLI, a function that runs per request, a test run, a notebook cell that opens a database and exits
+| The native build, `{native-pkg-name}`. It starts faster and holds less memory than the JVM build.
+
+| Long-lived, with heavy repeated scans or big loads
+| The JVM build, `{pkg-name}`. The JVM warms up and then runs long scans and bulk loads faster than the native build.
+
+| Several processes or services read and write the same database
+| The server, with a driver. An embedded database is owned by one process; see xref:index.adoc#embedded-vs-http[Embedded bindings or the HTTP driver].
+|===
+
+Which build is ahead depends on whether you measure the first pass after a start or the warm passes, so measure with your own data before you commit to one. The two embedded packages expose the same API; xref:index.adoc#jvm-vs-native[JVM build or native build] compares them.
+
+== The embedded packages
+
+[cols="2,2,3"]
+|===
+| Package | Kind | What it is
+
+| `{pkg-name}`
+| Embedded, JVM build
+| The engine inside your Python process, through https://jpype.readthedocs.io/[JPype], with a bundled Java runtime. Import it as `{import-name}`. This is the package this component documents.
+
+| `{native-pkg-name}`
+| Embedded, GraalVM native build (preview)
+| The same API with the engine compiled ahead of time: no JVM and no JPype. Import it as `{native-import-name}`.
+
+| `{short-pkg-name}`
+| Embedded, JVM build
+| The name `{pkg-name}` moves to in the middle of November. Until then a placeholder on PyPI that installs `{pkg-name}`.
+
+| `{short-native-pkg-name}`
+| Embedded, native build (preview)
+| The name `{native-pkg-name}` moves to at the same time. Until then an alias that installs it.
+
+| `{jvm-pkg-name}`
+| Embedded, JVM build
+| A reserved name for the JVM build. Until the move it installs `{pkg-name}`.
+|===
+
+[[drivers]]
+== Packages that talk to a server
+
+None of these contains the engine. They connect to a running ArcadeDB server.
+
+* `{driver-pkg-name}`: the official HTTP client. See xref:arcadedb::how-to/connectivity/drivers/python-http.adoc[Python -- HTTP driver].
+* `{grpc-driver-pkg-name}`: the official gRPC client. See xref:arcadedb::how-to/connectivity/drivers/python-grpc.adoc[Python -- gRPC driver].
+* `{community-driver-pkg-name}`: a community HTTP driver by Steve Reiner and others ({community-repo-url}[stevereiner/arcadedb-python]). It is not related to this repository, whose name is also `arcadedb-python`. Check which one a tutorial installs before you copy its code.

docs/modules/ROOT/pages/quickstart.adoc

@@ -7,7 +7,7 @@ This page builds a small database from scratch. You need the package from xref:i
 
 == Embedded mode
 
-The database runs in your Python process. You use SQL for the schema and for CRUD, through two calls:
+The database runs in your Python process. You use SQL for the schema and for CRUD, through two calls. ArcadeDB SQL is its own dialect, and it has no JOINs: records link to each other and a query follows the links (see xref:arcadedb::reference/sql/sql-introduction.adoc#no-joins[No JOINs]).
 
 * `db.command(language, statement, *params)` runs a statement that can change data or schema.
 * `db.query(language, statement, *params)` runs a read.