robfrank · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -13,6 +13,8 @@ Two outputs, one source tree:
 - **HTML site (production)** — `docs.arcadedb.com` is the Antora build. The Antora playbook reads from `docs/modules/ROOT/{pages,images}/`, which is **regenerated from `src/main/asciidoc/` on every CI run by `scripts/migrate.sh`** (it wipes and rebuilds the `docs/modules/ROOT/` tree). Deploy workflow: `.github/workflows/cloudflare-deploy.yml` — on every push to `main` it does `npm ci` → `bash scripts/migrate.sh` → `npm run build` → `wrangler pages deploy build/site` to the `arcadedb-docs` Cloudflare Pages project.
 - **PDF (production)** — `ArcadeDB-Manual.pdf` is built by `mvn` from `src/main/asciidoc/` directly. Workflow: `.github/workflows/pdf.yml`.
 
+**Release number**: set the current ArcadeDB release once, in `src/main/asciidoc/version.adoc` (`:revnumber:`). The legacy build includes it, `generate-pdf-manual.py` reads it, and `scripts/sync-revnumber.py` (a `migrate.sh` step) copies it into `docs/antora.yml`. Write install and run snippets as `{revnumber}`; leave historical "since vX" notes as literals.
+
 **Where to edit content**: `src/main/asciidoc/` is the only place to edit. CI runs `scripts/migrate.sh` automatically on push to `main`, so you do **not** need to run it by hand. Only run it locally if you want to preview the Antora site before pushing.
 
 The legacy single-page Asciidoctor HTML build (`mvn generate-resources` → `target/generated-docs/index.html`) still works and is useful for quick local previews of `src/main/asciidoc/` edits, but it is no longer deployed anywhere — `docs.arcadedb.com` is Antora.

diff --git a/docs/antora.yml b/docs/antora.yml
@@ -6,7 +6,9 @@ nav:
   - modules/ROOT/nav-query.adoc
 asciidoc:
   attributes:
-    revnumber: '26.10.2'
+    # Synced from src/main/asciidoc/version.adoc by scripts/sync-revnumber.py
+    # (run by migrate.sh). Change the release there, not here.
+    revnumber: '26.11.1'
     project-name: 'ArcadeDB'
     site-url: 'https://docs.arcadedb.com'
     repo-url: 'https://github.com/ArcadeData/arcadedb'

diff --git a/pom.xml b/pom.xml
@@ -10,7 +10,7 @@
 
     <groupId>com.arcadedb</groupId>
     <artifactId>arcadedb-doc</artifactId>
-    <version>26.10.2</version>
+    <version>26.11.1</version>
     <packaging>war</packaging>
 
     <properties>

diff --git a/scripts/generate-pdf-manual.py b/scripts/generate-pdf-manual.py
@@ -23,6 +23,17 @@
 PDF_DIR = REPO / "docs" / "pdf"
 PDF_PAGES = PDF_DIR / "pages"  # stripped page copies for the PDF aggregator
 
+VERSION_FILE = REPO / "src" / "main" / "asciidoc" / "version.adoc"
+
+
+def read_revnumber() -> str:
+    """The current release, from version.adoc (the one place it is set)."""
+    m = re.search(r"^:revnumber:\s*(\S+)\s*$", VERSION_FILE.read_text(encoding="utf-8"), re.M)
+    if not m:
+        sys.exit(f"no :revnumber: line in {VERSION_FILE}")
+    return m.group(1)
+
+
 NAV_FILES = ["nav.adoc", "nav-query.adoc"]
 
 XREF_RE = re.compile(r"xref:([^\[\s#]+\.adoc)(?:#[^\[\s]+)?\[([^\]]*)\]")
@@ -101,7 +112,7 @@ def main() -> int:
 
     out: list[str] = [
         "= ArcadeDB Manual",
-        ":revnumber: 26.10.2",
+        f":revnumber: {read_revnumber()}",
         ":doctype: book",
         ":imagesdir: ../modules/ROOT/images",
         ":source-highlighter: rouge",

diff --git a/scripts/migrate.sh b/scripts/migrate.sh
@@ -26,7 +26,6 @@ echo "==> Copying .adoc tree from $SRC"
 cp -R "$SRC"/tutorials       "$DEST_PAGES"/
 cp -R "$SRC"/use-cases       "$DEST_PAGES"/
 cp -R "$SRC"/concepts        "$DEST_PAGES"/
-cp -R "$SRC"/core-concepts   "$DEST_PAGES"/
 cp -R "$SRC"/how-to          "$DEST_PAGES"/
 cp -R "$SRC"/reference       "$DEST_PAGES"/
 cp -R "$SRC"/tools           "$DEST_PAGES"/
@@ -69,6 +68,9 @@ python3 scripts/add-descriptions.py
 echo "==> Generating nav.adoc"
 python3 scripts/generate-nav.py
 
+echo "==> Syncing revnumber into docs/antora.yml"
+python3 scripts/sync-revnumber.py
+
 echo "==> Generating PDF aggregator"
 python3 scripts/generate-pdf-manual.py
 

diff --git a/scripts/sync-revnumber.py b/scripts/sync-revnumber.py
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+Copy the release number from src/main/asciidoc/version.adoc into the
+`revnumber` attribute of docs/antora.yml.
+
+version.adoc is the one place to set the current ArcadeDB release. The
+legacy single-page build includes it directly, generate-pdf-manual.py
+reads it for the PDF, and this script feeds it to Antora, so install and
+run snippets written as `{revnumber}` show the same release everywhere.
+
+Idempotent: rewrites antora.yml only when the value differs.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+VERSION_FILE = REPO / "src" / "main" / "asciidoc" / "version.adoc"
+ANTORA_YML = REPO / "docs" / "antora.yml"
+
+VERSION_RE = re.compile(r"^:revnumber:\s*(\S+)\s*$", re.M)
+ANTORA_RE = re.compile(r"^(\s*revnumber:\s*)'[^']*'\s*$", re.M)
+
+
+def read_revnumber() -> str:
+    m = VERSION_RE.search(VERSION_FILE.read_text(encoding="utf-8"))
+    if not m:
+        sys.exit(f"no :revnumber: line in {VERSION_FILE}")
+    return m.group(1)
+
+
+def main() -> int:
+    rev = read_revnumber()
+    text = ANTORA_YML.read_text(encoding="utf-8")
+    if not ANTORA_RE.search(text):
+        sys.exit(f"no revnumber attribute in {ANTORA_YML}")
+    new = ANTORA_RE.sub(lambda m: f"{m.group(1)}'{rev}'", text, count=1)
+    if new != text:
+        ANTORA_YML.write_text(new, encoding="utf-8")
+    print(f"revnumber: {rev}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/templates/_redirects b/scripts/templates/_redirects
@@ -8,6 +8,8 @@
 # Pages that moved or were merged, still linked from outside and reported as
 # 404 by Google Search Console. Each old URL is listed with and without .html.
 /arcadedb/tools/studio                         /arcadedb/tools/studio/chapter  301
+/arcadedb/core-concepts/chapter                /arcadedb/concepts/chapter  301
+/arcadedb/core-concepts/chapter.html           /arcadedb/concepts/chapter  301
 /arcadedb/tools/studio.html                    /arcadedb/tools/studio/chapter  301
 /arcadedb/tools/studio/graph                   /arcadedb/tools/studio/query#studio-query-graph  301
 /arcadedb/tools/studio/graph.html              /arcadedb/tools/studio/query#studio-query-graph  301

diff --git a/scripts/templates/get-started.adoc b/scripts/templates/get-started.adoc
@@ -83,7 +83,7 @@
   <a class="tutorial-card" href="tutorials/vector-search-tutorial.html">
     <span class="tutorial-card-eyebrow">Vector search</span>
     <h3>Vector Search Tutorial</h3>
-    <p>Build an HNSW index and run cosine-similarity queries for semantic search.</p>
+    <p>Build an <code>LSM_VECTOR</code> index and run cosine-similarity queries for semantic search.</p>
   </a>
   <a class="tutorial-card" href="tutorials/time-series-tutorial.html">
     <span class="tutorial-card-eyebrow">Time series</span>

diff --git a/scripts/templates/index.adoc b/scripts/templates/index.adoc
@@ -279,7 +279,7 @@ Step-by-step guides to learn ArcadeDB's data models, query languages, and driver
   <a class="tutorial-card" href="tutorials/vector-search-tutorial.html">
     <span class="tutorial-card-eyebrow">Vectors &amp; AI</span>
     <h3>Vector Search Tutorial</h3>
-    <p>Build a semantic-search index with HNSW and run cosine-similarity queries.</p>
+    <p>Build an <code>LSM_VECTOR</code> semantic-search index and run cosine-similarity queries.</p>
   </a>
   <a class="tutorial-card" href="tutorials/time-series-tutorial.html">
     <span class="tutorial-card-eyebrow">Time Series</span>

diff --git a/src/main/asciidoc/concepts/vector-search.adoc b/src/main/asciidoc/concepts/vector-search.adoc
@@ -1,6 +1,6 @@
 [[vector-model]]
 [[vector-search-concepts]]
-=== Vector
+=== Vector Search
 
 ArcadeDB includes a native vector search engine for similarity-based retrieval of embeddings. Vector indexes are fully integrated into the SQL query engine and support ACID transactions, persistent storage, and automatic compaction.
 

diff --git a/src/main/asciidoc/core-concepts/chapter.adoc b/src/main/asciidoc/core-concepts/chapter.adoc
diff --git a/src/main/asciidoc/how-to/chapter.adoc b/src/main/asciidoc/how-to/chapter.adoc
@@ -2,6 +2,10 @@
 == How-To Guides
 :description: ArcadeDB how-to guides: data modeling, BI and analytics integrations, server operations such as backup, HA and Kubernetes, and migrating data into ArcadeDB.
 
+How-to guides are task-oriented recipes for an ArcadeDB you already have running.
+Each one answers a single question, such as how to add a full-text index, plug in Grafana, back up a database, run a cluster on Kubernetes or import a Neo4j export, and links to the reference pages for every option it uses.
+For a first walkthrough start with the tutorials, and for the ideas behind the steps read the concepts.
+
 include::data-modeling/chapter.adoc[]
 
 include::integrations/chapter.adoc[]

diff --git a/src/main/asciidoc/how-to/connectivity/c.adoc b/src/main/asciidoc/how-to/connectivity/c.adoc
@@ -1,5 +1,5 @@
 [[http-api-c]]
-==== C
+==== Connecting from C
 :description: Connect to ArcadeDB from C using the PostgreSQL wire protocol with libpq to run SQL, or the HTTP/JSON API with libcurl and no driver. Sample code included.
 
 [TIP]

diff --git a/src/main/asciidoc/how-to/connectivity/drivers/go-grpc.adoc b/src/main/asciidoc/how-to/connectivity/drivers/go-grpc.adoc
@@ -1,5 +1,5 @@
 [[driver-go-grpc]]
-==== Go -- gRPC Driver
+==== Go gRPC Driver
 
 `github.com/ArcadeData/arcadedb-drivers/go/arcadedbgrpc` is ArcadeDB's Go gRPC client, generated
 from the server's Protobuf contract. A small facade on top handles authentication, the streaming

diff --git a/src/main/asciidoc/how-to/connectivity/drivers/go-http.adoc b/src/main/asciidoc/how-to/connectivity/drivers/go-http.adoc
@@ -1,5 +1,5 @@
 [[driver-go-http]]
-==== Go -- HTTP Driver
+==== Go HTTP Driver
 
 `github.com/ArcadeData/arcadedb-drivers/go/arcadedb` is ArcadeDB's Go HTTP client, generated from
 the server's OpenAPI contract. A hand-written facade on top covers queries, commands,

diff --git a/src/main/asciidoc/how-to/connectivity/drivers/js-grpc.adoc b/src/main/asciidoc/how-to/connectivity/drivers/js-grpc.adoc
@@ -1,5 +1,5 @@
 [[driver-js-grpc]]
-==== JavaScript / TypeScript -- gRPC Driver
+==== JavaScript / TypeScript gRPC Driver
 
 `@arcadedb/driver-grpc` is ArcadeDB's TypeScript/JavaScript gRPC client, generated from the
 server's Protobuf contract. It wraps the generated https://connectrpc.com/[Connect] client in a

diff --git a/src/main/asciidoc/how-to/connectivity/drivers/js-http.adoc b/src/main/asciidoc/how-to/connectivity/drivers/js-http.adoc
@@ -1,5 +1,5 @@
 [[driver-js-http]]
-==== JavaScript / TypeScript -- HTTP Driver
+==== JavaScript / TypeScript HTTP Driver
 
 `@arcadedb/driver` is ArcadeDB's TypeScript/JavaScript HTTP client, generated from the server's
 OpenAPI contract.

diff --git a/src/main/asciidoc/how-to/connectivity/drivers/python-grpc.adoc b/src/main/asciidoc/how-to/connectivity/drivers/python-grpc.adoc
@@ -1,5 +1,5 @@
 [[driver-python-grpc]]
-==== Python -- gRPC Driver
+==== Python gRPC Driver
 
 `arcadedb-driver-grpc` is ArcadeDB's Python gRPC client, generated from the server's Protobuf
 contract. It wraps the generated stub in a small facade for streaming queries, streaming inserts

diff --git a/src/main/asciidoc/how-to/connectivity/drivers/python-http.adoc b/src/main/asciidoc/how-to/connectivity/drivers/python-http.adoc
@@ -1,5 +1,5 @@
 [[driver-python-http]]
-==== Python -- HTTP Driver
+==== Python HTTP Driver
 
 `arcadedb-driver` is ArcadeDB's Python HTTP client, generated from the server's OpenAPI contract.
 It wraps queries, commands and transactions in a small facade over

diff --git a/src/main/asciidoc/how-to/connectivity/http-csharp.adoc b/src/main/asciidoc/how-to/connectivity/http-csharp.adoc
@@ -1,5 +1,5 @@
 [[http-api-csharp]]
-==== C#
+==== Connecting from C#
 :description: Connect to ArcadeDB from C# and .NET through the Neo4j BOLT driver, the Npgsql PostgreSQL driver, or the HTTP/JSON API with HttpClient. Sample code included.
 
 [TIP]

diff --git a/src/main/asciidoc/how-to/connectivity/http-elixir.adoc b/src/main/asciidoc/how-to/connectivity/http-elixir.adoc
@@ -1,5 +1,5 @@
 [[http-api-elixir]]
-==== Elixir
+==== Connecting from Elixir
 :description: Connect to ArcadeDB from Elixir through the HTTP/JSON API: configure the HTTP client, then send SQL commands and queries with working sample code.
 
 [TIP]

diff --git a/src/main/asciidoc/how-to/connectivity/python-embedded.adoc b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc
@@ -1,5 +1,5 @@
 [[python-embedded]]
-==== Python -- Embedded Bindings
+==== Python Embedded Bindings
 
 The embedded bindings run the ArcadeDB engine inside your Python process, so there is no network hop and no server to start. They ship as two packages, and both import as `arcadedb`:
 

diff --git a/src/main/asciidoc/how-to/connectivity/r.adoc b/src/main/asciidoc/how-to/connectivity/r.adoc
@@ -1,5 +1,5 @@
 [[http-api-r]]
-==== R
+==== Connecting from R
 :description: Connect to ArcadeDB from R using the PostgreSQL wire protocol with RPostgres and DBI to run SQL, or the HTTP/JSON API with httr2. Sample code included.
 
 [TIP]

diff --git a/src/main/asciidoc/how-to/connectivity/ruby.adoc b/src/main/asciidoc/how-to/connectivity/ruby.adoc
@@ -1,5 +1,5 @@
 [[http-api-ruby]]
-==== Ruby
+==== Connecting from Ruby
 
 [TIP]
 ====

diff --git a/src/main/asciidoc/how-to/connectivity/rust.adoc b/src/main/asciidoc/how-to/connectivity/rust.adoc
@@ -1,5 +1,5 @@
 [[http-api-rust]]
-==== Rust
+==== Connecting from Rust
 :description: Connect to ArcadeDB from Rust with the neo4rs crate over Neo4j BOLT, the postgres crate over the PostgreSQL wire protocol, or reqwest over HTTP/JSON.
 
 [TIP]

diff --git a/src/main/asciidoc/how-to/operations/docker.adoc b/src/main/asciidoc/how-to/operations/docker.adoc
@@ -1,5 +1,5 @@
 [[docker]]
-==== Docker
+==== Running ArcadeDB with Docker
 
 To run the ArcadeDB server with Docker, type this (replace <password> with the root password you want to use):
 

diff --git a/src/main/asciidoc/how-to/operations/ha.adoc b/src/main/asciidoc/how-to/operations/ha.adoc
@@ -1,5 +1,5 @@
 [[howto-high-availability]]
-==== High Availability
+==== Configuring High Availability
 
 ArcadeDB supports a High Availability (HA) mode where multiple servers share the same databases via Raft-based replication.
 All servers of a cluster serve the same set of databases.

diff --git a/src/main/asciidoc/how-to/operations/kubernetes.adoc b/src/main/asciidoc/how-to/operations/kubernetes.adoc
@@ -1,5 +1,5 @@
 [[kubernetes]]
-==== Kubernetes
+==== Running ArcadeDB on Kubernetes
 
 ArcadeDB officially supports deployment on Kubernetes via the https://github.com/ArcadeData/arcadedb-helm[arcadedb-helm] chart, published at `https://helm.arcadedb.com/`.
 The chart deploys ArcadeDB as a `StatefulSet` and, when `replicaCount` is greater than 1, automatically configures a Raft-based <<howto-high-availability,High Availability>> cluster.

diff --git a/src/main/asciidoc/reference/cypher/chapter.adoc b/src/main/asciidoc/reference/cypher/chapter.adoc
@@ -69,9 +69,6 @@ include::cypher-gql-conformance.adoc[]
 
 include::cypher-tutorial.adoc[]
 
-[[cypher-commands]]
-==== Clauses Reference
-
 include::cypher-clauses.adoc[]
 
 include::cypher-expressions.adoc[]
diff --git a/src/main/asciidoc/reference/cypher/cypher-clauses.adoc b/src/main/asciidoc/reference/cypher/cypher-clauses.adoc
@@ -1,3 +1,7 @@
+[[cypher-commands]]
+==== Cypher Clauses Reference
+:description: Cypher clauses in ArcadeDB: MATCH, OPTIONAL MATCH, WHERE, RETURN, WITH, CREATE, MERGE, SET, DELETE, UNWIND, CALL, ORDER BY and every other supported clause.
+
 [[cypher-match]]
 ===== MATCH
 

diff --git a/src/main/asciidoc/reference/graphql/chapter.adoc b/src/main/asciidoc/reference/graphql/chapter.adoc
@@ -1,4 +1,7 @@
 :description: Query ArcadeDB with GraphQL: the supported subset of the GraphQL specification, defining types, running queries over HTTP, and the arcadedb-graphql library.
 [[graphql-reference]]
+ifdef::site-gen-antora[]
+=== GraphQL Reference
+endif::[]
 
 include::graphql.adoc[]
diff --git a/src/main/asciidoc/reference/gremlin/chapter.adoc b/src/main/asciidoc/reference/gremlin/chapter.adoc
@@ -1,4 +1,7 @@
 :description: Run Apache TinkerPop Gremlin 3.7 queries on ArcadeDB, embedded through the arcadedb-gremlin library or remotely through the bundled Gremlin Server.
 [[gremlin-reference]]
+ifdef::site-gen-antora[]
+=== Gremlin Reference
+endif::[]
 
 include::gremlin.adoc[]
diff --git a/src/main/asciidoc/reference/java-api/chapter.adoc b/src/main/asciidoc/reference/java-api/chapter.adoc
@@ -1,4 +1,6 @@
 [[java-api-reference]]
+=== Java API Reference
+:description: ArcadeDB Java API reference: database and async APIs, schema, events, embedded documents, the Select API, batch importer, vectors, and the remote and gRPC clients.
 
 include::java-ref-database.adoc[]
 

diff --git a/src/main/asciidoc/reference/java-api/java-schema.adoc b/src/main/asciidoc/reference/java-api/java-schema.adoc
@@ -1,5 +1,5 @@
 [[getschema]]
-==== Schema
+==== Java Schema API
 
 ArcadeDB can work in schema-less mode (like most of NoSQL DBMS), schema-full (like with RDBMS) or hybrid.
 The main API to manage the schema is the Schema interface you can obtain by calling the API <<getschema,`db.getSchema()`>>:

diff --git a/src/main/asciidoc/reference/mongodb-ql/chapter.adoc b/src/main/asciidoc/reference/mongodb-ql/chapter.adoc
@@ -1,4 +1,7 @@
 :description: Use the MongoDB query language and wire protocol with ArcadeDB: enable the MongoDB plugin on the server, or add the arcadedb-mongodbw library when embedded.
 [[mongodb-ql-reference]]
+ifdef::site-gen-antora[]
+=== MongoDB Query Language Reference
+endif::[]
 
 include::mongo.adoc[]
diff --git a/src/main/asciidoc/reference/mongodb-ql/mongo.adoc b/src/main/asciidoc/reference/mongodb-ql/mongo.adoc
@@ -1,5 +1,5 @@
 [[mongodb-query-language]]
-=== Mongo
+=== MongoDB Query Language
 
 ArcadeDB provides support for both MongoDB Query Language and MongoDB protocol.
 

diff --git a/src/main/asciidoc/reference/redis-ql/chapter.adoc b/src/main/asciidoc/reference/redis-ql/chapter.adoc
@@ -1,4 +1,7 @@
 :description: Talk to ArcadeDB over the Redis protocol: the supported subset of Redis commands, enabling the Redis plugin on the server, and the arcadedb-redisw library.
 [[redis-ql-reference]]
+ifdef::site-gen-antora[]
+=== Redis Protocol Reference
+endif::[]
 
 include::redis.adoc[]
diff --git a/src/main/asciidoc/reference/redis-ql/redis.adoc b/src/main/asciidoc/reference/redis-ql/redis.adoc
@@ -1,5 +1,5 @@
 [[redis-query-language]]
-=== Redis
+=== Redis Protocol
 
 ArcadeDB Server supports a subset of the https://redis.io[Redis] protocol.
 Please open an issue or a discussion on GitHub to support more commands.

diff --git a/src/main/asciidoc/reference/sql/chapter.adoc b/src/main/asciidoc/reference/sql/chapter.adoc
@@ -1,5 +1,5 @@
 [[sql]]
-=== SQL
+=== SQL Reference
 :description: ArcadeDB SQL reference: every command for querying, graph traversal, schema and database management, plus SQL functions, methods and APOC-compatible functions.
 
 *Overview Commands*

diff --git a/src/main/asciidoc/reference/sql/sql-indexes.adoc b/src/main/asciidoc/reference/sql/sql-indexes.adoc
@@ -1,5 +1,5 @@
 [[sql-indexes]]
-==== Indexes
+==== SQL Indexes
 :description: Manage ArcadeDB indexes with SQL: CREATE INDEX for unique, non-unique, full-text and vector indexes, plus REBUILD INDEX, COMPACT INDEX and DROP INDEX.
 
 [[sql-create-index]]