docs(ui): readable tables and a clear "On this page" menu at every width; link the Python docs

docs/ui/supplemental/css/arcadedb.css

@@ -196,8 +196,10 @@ a:hover, a:focus {
   min-width: 360px;
 }
 
-/* Antora right TOC ("On this page") */
-aside.toc.sidebar, .toc-menu { background: transparent; border-left: 1px solid var(--color-border-light); }
+/* Antora right TOC ("On this page"). One rule line, on the menu, with room before the links:
+   the aside and the menu both drew it, and the links started 1px from it. */
+aside.toc.sidebar { background: transparent; }
+.toc-menu { background: transparent; border-left: 1px solid var(--color-border-light); padding-left: 0.75rem; }
 .toc-menu .title, aside.toc .title { font-family: var(--font-heading); color: var(--color-text-primary); font-weight: 700; text-transform: uppercase; letter-spacing: 0.05em; font-size: 0.75em; }
 .toc-menu a { color: var(--color-text-secondary); }
 .toc-menu a:hover, .toc-menu li.is-active > a { color: var(--color-primary); }
@@ -279,36 +281,49 @@ aside.toc.sidebar, .toc-menu { background: transparent; border-left: 1px solid v
   border-radius: 8px;
   border-collapse: separate;
   border-spacing: 0;
-  overflow: hidden;
-  width: 100%;
+  /* As wide as the content needs, up to the content column; wider content scrolls sideways
+     (the GitHub markdown pattern) instead of running under the "On this page" sidebar. */
+  display: block;
+  width: max-content;
   max-width: 100%;
+  overflow-x: auto;
 }
-/* Allow long identifiers and inline code to wrap inside table cells.
-   Without this, names like `arcadedb.ha.stopServerOnReplicationFailure`
-   force a column wider than the content area and the table overflows
-   under the right-side "On this page" sidebar. */
+/* Text wraps at spaces and splits a word only when it cannot fit on its own line; no automatic
+   hyphenation (it split words such as "Pack-age"). Long inline code, such as
+   `arcadedb.ha.stopServerOnReplicationFailure`, may still wrap anywhere. */
 .doc table.tableblock td,
 .doc table.tableblock th {
-  word-break: break-word;
-  overflow-wrap: anywhere;
+  word-break: normal;
+  overflow-wrap: break-word;
+  hyphens: manual;
 }
 .doc table.tableblock td code,
 .doc table.tableblock th code {
   white-space: normal;
-  word-break: break-all;
+  word-break: normal;
   overflow-wrap: anywhere;
 }
+/* On a phone or a small tablet a multi-column table scrolls sideways instead of squeezing
+   every column to a few characters. */
+@media (max-width: 768px) {
+  .doc table.tableblock td,
+  .doc table.tableblock th { min-width: 7.5rem; }
+  /* The last column usually holds the prose (description, notes): give it a reading width, so a phone
+     scrolls the table sideways instead of folding the text into a column a few words wide. */
+  .doc table.tableblock td:last-child,
+  .doc table.tableblock th:last-child { min-width: 14rem; }
+}
 .doc table.tableblock thead tr th {
   background: var(--color-bg-secondary);
   color: var(--color-text-primary);
   font-weight: 600;
   font-family: var(--font-body);
-  padding: 12px 16px;
+  padding: 12px;
   border-bottom: 1px solid var(--color-border);
 }
 .doc table.tableblock tbody tr td,
 .doc table.tableblock tbody tr th {
-  padding: 12px 16px;
+  padding: 12px;
   border-bottom: 1px solid var(--color-border);
   color: var(--color-text-secondary);
 }

src/main/asciidoc/concepts/transactions.adoc

@@ -255,7 +255,7 @@ flushing on its own (group commit, setting `arcadedb.txWalGroupCommit`, on by de
 on disk, but it no longer holds the locks of the files it wrote while its WAL is written and flushed, so the commits that
 arrive meanwhile are written and flushed together. On an Apple silicon laptop, 50 clients writing into the same type went
 from about 230 to about 4,000 commits per second with `txWalFlush=2`. A single writer sees no difference. The
-<<engine-gauges,engine metrics>> `wal.group.*` and `commit.lock.*` show how many commits each flush served and how long
+<<engine-gauges,engine metrics>> `+wal.group.*+` and `+commit.lock.*+` show how many commits each flush served and how long
 a commit holds its locks.
 
 What changes compared to the previous versions:
@@ -364,6 +364,7 @@ A `ConcurrentModificationException` always means another transaction wrote the r
 In particular, updating a record that the same transaction has already deleted is not a conflict, it simply has no effect - the delete wins, since the record will not exist once the transaction commits.
 The order of the two operations does not matter.
 
+[[statement-fails-halfway]]
 ==== A statement that fails halfway
 
 A statement that fails inside a transaction you keep is taken back on its own, and the transaction goes on as if the statement had never run, the way SQLite undoes a failed statement.

src/main/asciidoc/how-to/connectivity/postgres.adoc

@@ -229,7 +229,7 @@ dropping it, finds the views that depend on it. Dependencies are listed per type
 _Since v26.10.1_, `pg_type` can also be queried on its own, and not only as part of a column list. Some
 clients build a map of every type the server has before they run a single query, and refuse to connect if
 that map comes back empty - the Apache Arrow ADBC PostgreSQL driver is one of them. Such a query is answered
-with the types this protocol can actually produce (see <<Column type mapping,Column type mapping>> below),
+with the types this protocol can actually produce (see <<postgres-column-type-mapping,Column type mapping>> below),
 each described the way PostgreSQL describes it. A filter the server cannot interpret returns no rows rather
 than every type, so a client asking whether an extension type such as `hstore` exists is correctly told it
 does not.
@@ -407,6 +407,7 @@ PROGRAM`, which would let a wire client write files or run commands on the serve
 without a binary encoding on this server (an array) is refused the same way; export it in text or CSV format, or
 project it as a string.
 
+[[postgres-column-type-mapping]]
 ===== Column type mapping
 
 A column's advertised PostgreSQL type must not depend on whether the query happens to return any rows - a

src/main/asciidoc/how-to/connectivity/python-embedded.adoc

@@ -8,7 +8,7 @@ The embedded bindings run the ArcadeDB engine inside your Python process, so the
 
 Install one of them, not both. With both installed, `import arcadedb` raises an `ImportError` that names the two.
 
-The bindings live in the https://github.com/ArcadeData/arcadedb-python[ArcadeData/arcadedb-python] repository. This page covers the first steps; the repository holds the full guides and the API reference.
+The bindings live in the https://github.com/ArcadeData/arcadedb-python[ArcadeData/arcadedb-python] repository, and their guides are in the https://docs.arcadedb.com/arcadedb-python/[ArcadeDB Python] docs. This page covers the first steps.
 
 ===== Install
 
@@ -101,6 +101,7 @@ You can also combine the two. The bindings can start an in-process HTTP server (
 
 ===== Where to go next
 
-* https://github.com/ArcadeData/arcadedb-python[Bindings repository]: guides for vectors, graphs, time series, import and server mode, plus the API reference and examples.
+* https://docs.arcadedb.com/arcadedb-python/[ArcadeDB Python docs]: installation, which package to pick, databases and queries, concurrency, bulk loads and vectors.
+* https://github.com/ArcadeData/arcadedb-python[Bindings repository]: the source, the examples and the issue tracker.
 * xref:how-to/connectivity/drivers/native-drivers.adoc[Native drivers]: the HTTP and gRPC clients, if you would rather talk to a server.
 * xref:tutorials/python-quickstart.adoc[Python quickstart]: the PostgreSQL wire protocol route.

src/main/asciidoc/how-to/data-modeling/graph-olap.adoc

@@ -456,7 +456,7 @@ GraphAnalyticalView roads = GraphAnalyticalView.builder(database)
     .build();
 ----
 
-Queries go through <<algo-cch-shortest-path,algo.cch.shortestPath>> (Cypher) or <<cchShortestPath,cchShortestPath()>> (SQL). A query is answered by the hierarchy when its weight property and relationship types are exactly those of a hierarchy on a ready view; otherwise, and whenever the hierarchy cannot answer for the view's current state, it is answered by bidirectional Dijkstra. Answers are exact either way, and a transaction holding uncommitted changes always sees them.
+Queries go through <<algo-cch-shortest-path,algo.cch.shortestPath>> (Cypher) or <<cch-shortest-path,cchShortestPath()>> (SQL). A query is answered by the hierarchy when its weight property and relationship types are exactly those of a hierarchy on a ready view; otherwise, and whenever the hierarchy cannot answer for the view's current state, it is answered by bidirectional Dijkstra. Answers are exact either way, and a transaction holding uncommitted changes always sees them.
 
 *How it works*
 
@@ -579,14 +579,14 @@ counted on its own, by its own push-down or plan, and the counts are multiplied.
 least one row. Two parts of one `MATCH` clause are multiplied only when the schema proves their relationships cannot
 be the same edge, since a clause binds every relationship once. A product that does not fit a 64-bit integer is an
 error (issue #9596).
-* a `WITH` that only passes variables on, `*` and aliases included (`WITH message, creator`, `WITH m AS x`), with no
+* a `WITH` that only passes variables on, `+*+` and aliases included (`WITH message, creator`, `WITH m AS x`), with no
 aggregation, `DISTINCT`, `WHERE`, `ORDER BY`, `SKIP` or `LIMIT`: it leaves the number of rows alone, so the statement
 is counted as if the clauses on both sides were one query part (issue #9597).
-* `count(x)` of a node or relationship variable a non-optional `MATCH` binds, which counts the same rows as `count(*)`;
+* `count(x)` of a node or relationship variable a non-optional `MATCH` binds, which counts the same rows as `+count(*)+`;
 a single relationship between two unconstrained nodes, `MATCH ()-[e:KNOWS]->() RETURN count(e)` (untyped, with several
 types or undirected too), read from the view's per-type totals, or without a view in one walk of the edge lists that
 loads no edge; and `MATCH (n) RETURN count(n)`, the sum of the vertex types' counters (issue #9600). Unlike the SQL
-`SELECT count(*) FROM KNOWS`, which counts edge records, the relationship count includes lightweight edges, which keep no
+`+SELECT count(*) FROM KNOWS+`, which counts edge records, the relationship count includes lightweight edges, which keep no
 record.
 * the same pattern however it is written: the comma-separated parts of a `MATCH` are read as the graph they describe, so a
 chain cut into parts is counted as the chain, and a cycle such as LSQB Q2 (a `KNOWS` hop closed by a three-hop chain, or
@@ -608,9 +608,9 @@ must be undirected, anonymous and of one type, and the three variables carry one
 `COUNT TRIANGLES (CSR sorted intersection)` with the order it counts.
 
 *Multi-hop chains on the view.* A chain of labeled hops such as `MATCH (a:P)-[:K]->(b:P)-[:K]->(c:P)` is walked on the
-view (`EXPLAIN` shows `GAVFusedChain`). Since v26.10.2 a `count(*)`, or `count(x)` of a variable of the chain, is counted
+view (`EXPLAIN` shows `GAVFusedChain`). Since v26.10.2 a `+count(*)+`, or `count(x)` of a variable of the chain, is counted
 during the walk with up to two grouping keys that are chain variables, in a `RETURN` or a `WITH`
-(`RETURN a, count(*) AS n`); `EXPLAIN` shows it on the chain as `fused count(*) AS n`. When the statement returns the
+(`+RETURN a, count(*) AS n+`); `EXPLAIN` shows it on the chain as `+fused count(*) AS n+`. When the statement returns the
 paths' rows instead, they are produced in bounded batches, so memory no longer grows with the number of paths and a
 `LIMIT` stops the walk early (issue #9738). If the view is rebuilt while such a result is still being read, the query
 fails with a retryable error rather than mixing rows from two builds: run it again.

src/main/asciidoc/how-to/integrations/grafana.adoc

@@ -12,7 +12,7 @@ The https://github.com/ArcadeData/arcadedb-grafana-datasource[ArcadeDB Grafana p
 *Features:*
 
 * **Time Series mode** - visual query builder with auto-discovered types, fields, tags, and aggregation functions (SUM, AVG, MIN, MAX, COUNT)
-* **SQL mode** - ArcadeDB SQL with macro expansion (`$__timeFrom`, `$__timeTo`, `$__timeFilter(col)`, `$__interval`)
+* **SQL mode** - ArcadeDB SQL with macro expansion (`+$__timeFrom+`, `+$__timeTo+`, `+$__timeFilter(col)+`, `+$__interval+`)
 * **Cypher mode** - OpenCypher queries with optional Node Graph visualization
 * **Gremlin mode** - Apache Gremlin traversals with optional Node Graph visualization
 * **Alerting** - full Grafana alerting support via the Go backend

src/main/asciidoc/how-to/migration/importer.adoc

@@ -80,7 +80,7 @@ Parsed 362000 (54256/sec) - 0 documents (0/sec) - 164118 vertices (5260/sec) - 3
 ----
 
 An RDF source is recognised from the shape of its first statement - `subject predicate object` with an optional
-closing `.` - so quoted literal objects, language tags (`@en`), typed literals (`^^<datatype>`), blank nodes (`_:b1`)
+closing `.` - so quoted literal objects, language tags (`@en`), typed literals (`^^<datatype>`), blank nodes (`+_:b1+`)
 and Windows (CRLF) line endings are all read as RDF, and the character separating the terms is used as the field
 delimiter. _(Since v26.10.1: a file using any of those was analysed as delimited text instead and the import failed
 with a number-parsing error naming an IRI. If a file still cannot be recognised, set the separator explicitly with

src/main/asciidoc/how-to/operations/ha.adoc

@@ -692,7 +692,7 @@ With ephemeral Raft storage, wiping the log on restart could leave the cluster i
 
 Durable storage lets a restarted node rejoin by *replaying its own persisted log* rather than always requiring a full snapshot resync from the leader.
 
-*Migration:* the per-node directory is named `raft-storage-<nodeName>` dynamically, which container runtimes and Kubernetes cannot mount as a volume (a wildcard like `raft-storage-*` is created as a literal directory, not expanded). Set `arcadedb.ha.raftStorageDirectory` to a *static* path (e.g. `/home/arcadedb/raft-storage`) and mount *that* path on durable storage before upgrading. On Kubernetes, back it with a `PersistentVolumeClaim` — see <<kubernetes,Kubernetes>>. On a plain filesystem you can instead copy the existing `raft-storage-<nodeName>` directory across the upgrade. A throwaway or test cluster that intentionally wants ephemeral behavior can opt out with `arcadedb.ha.raftPersistStorage=false`.
+*Migration:* the per-node directory is named `raft-storage-<nodeName>` dynamically, which container runtimes and Kubernetes cannot mount as a volume (a wildcard like `+raft-storage-*+` is created as a literal directory, not expanded). Set `arcadedb.ha.raftStorageDirectory` to a *static* path (e.g. `/home/arcadedb/raft-storage`) and mount *that* path on durable storage before upgrading. On Kubernetes, back it with a `PersistentVolumeClaim` — see <<kubernetes,Kubernetes>>. On a plain filesystem you can instead copy the existing `raft-storage-<nodeName>` directory across the upgrade. A throwaway or test cluster that intentionally wants ephemeral behavior can opt out with `arcadedb.ha.raftPersistStorage=false`.
 
 [[ha-remote-commit-contract]]
 ===== Committed-remotely response contract

src/main/asciidoc/how-to/operations/observability.adoc

@@ -171,7 +171,7 @@ grouped under `db="unknown"` rather than appearing one series per name.
 | `arcadedb.engine.commit.lock.handoffs` / `.commit.lock.handoff.seconds` | Those locks passed to a waiting commit, and the total time from the release to that commit running _(Since v26.11.1)_
 |===
 
-The `commit.lock.*` and `wal.group.*` counters are read as averages. `rate(...hold.seconds) / rate(...holds)` is how long
+The `+commit.lock.*+` and `+wal.group.*+` counters are read as averages. `rate(...hold.seconds) / rate(...holds)` is how long
 a commit keeps the files it writes locked, and with many clients writing into the same type it is what limits the commits
 per second: about 30 microseconds is normal, milliseconds mean the commits are waiting for the disk while they hold the
 locks (`arcadedb.txWalFlush` set to 1 or 2 with `arcadedb.txWalGroupCommit=false`). `rate(wal.group.commits) / rate(wal.group.commit.syncs)`

src/main/asciidoc/how-to/operations/upgrade.adoc

@@ -796,7 +796,7 @@ Every entry of `list queries` and `SHOW TRANSACTIONS` now carries the client tha
 [discrete]
 ====== 26.10.2 - Graph algorithms answer the incoming side of unidirectional edge types
 
-The `algo.*` and `path.*` procedures, the path-finding SQL functions (`dijkstra()`, `astar()`, `bellmanFord()`, `cchShortestPath()`, `duanSSSP()`) and the `node.degree*` / `node.relationship.*` functions now follow the edges of a `UNIDIRECTIONAL` type from their target too, as a Graph Analytical View already did (issue #8629). Before, they saw such an edge from its source only, so for example a walk with direction `IN` or `BOTH` missed it. `refactor.mergeNodes`, `refactor.cloneNodesWithRelationships` and changing a node's labels in Cypher no longer drop the incoming unidirectional edges of the node.
+The `+algo.*+` and `+path.*+` procedures, the path-finding SQL functions (`dijkstra()`, `astar()`, `bellmanFord()`, `cchShortestPath()`, `duanSSSP()`) and the `+node.degree*+` / `+node.relationship.*+` functions now follow the edges of a `UNIDIRECTIONAL` type from their target too, as a Graph Analytical View already did (issue #8629). Before, they saw such an edge from its source only, so for example a walk with direction `IN` or `BOTH` missed it. `refactor.mergeNodes`, `refactor.cloneNodesWithRelationships` and changing a node's labels in Cypher no longer drop the incoming unidirectional edges of the node.
 
 *Impact:* results over unidirectional edge types can change (more paths, higher in-degrees, different scores), and now match the results with a Graph Analytical View.
 
@@ -805,7 +805,7 @@ The `algo.*` and `path.*` procedures, the path-finding SQL functions (`dijkstra(
 [discrete]
 ====== 26.10.2 - Cypher counts match an undirected self loop once
 
-An undirected relationship pattern such as `(n)-[:KNOWS]-(m)` matches a self loop (an edge from a vertex to itself) once, as the openCypher specification and Neo4j do. The rows of such a pattern always did, but the counts computed without materializing the rows counted it twice: `MATCH (a)-[:KNOWS]-(b) RETURN count(*)`, a `count(*)` grouped by the start node, `OPTIONAL MATCH ... WITH n, count(m)` and the `COUNT { }` subquery, with and without a Graph Analytical View (issues #8750, #9540). The same release corrects the count of a chain with an inequality such as `WHERE a <> c` when the chain has a labelled or multi-hop part before or after the two positions the inequality compares.
+An undirected relationship pattern such as `(n)-[:KNOWS]-(m)` matches a self loop (an edge from a vertex to itself) once, as the openCypher specification and Neo4j do. The rows of such a pattern always did, but the counts computed without materializing the rows counted it twice: `+MATCH (a)-[:KNOWS]-(b) RETURN count(*)+`, a `+count(*)+` grouped by the start node, `OPTIONAL MATCH ... WITH n, count(m)` and the `COUNT { }` subquery, with and without a Graph Analytical View (issues #8750, #9540). The same release corrects the count of a chain with an inequality such as `WHERE a <> c` when the chain has a labelled or multi-hop part before or after the two positions the inequality compares.
 
 *Impact:* those counts can be lower than before on graphs with self loops, or on such chains, and now equal the number of rows the same `MATCH` returns.
 
@@ -949,7 +949,7 @@ A named Cypher constraint now records what its `CREATE CONSTRAINT` created, and
 *Action:* drop an old constraint by its index name, or through SQL (`DROP INDEX`, `ALTER PROPERTY ... MANDATORY false`). See <<cypher-drop-constraint,`DROP CONSTRAINT`>>.
 
 [discrete]
-====== 26.10.2 - The `path.*` procedures answer as `apoc.path.*` does
+====== 26.10.2 - The `+path.*+` procedures answer as `+apoc.path.*+` does
 
 `path.expandconfig` now reads its `uniqueness` option, with the APOC default `RELATIONSHIP_PATH`, and `path.expand` is breadth-first with `RELATIONSHIP_PATH` (issue #10049). Before, the breadth-first walk was always `NODE_GLOBAL` and the depth-first walk and `path.expand` always `NODE_PATH`. `path.subgraphall` returns every relationship between the returned nodes, whatever the `relationshipFilter` (issue #10048). `relationshipFilter` and `labelFilter` read the APOC syntax, and an unknown relationship type or label is refused (issue #10025).