docs(gfql): start-here nav with perf/reference hubs; result-first benchmark pages

CHANGELOG.md

@@ -47,6 +47,18 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 * GFQL: the general chain path keeps integer and boolean node attribute dtypes on a closed graph: the endpoint-closure backfill now appends only endpoints missing from the node frame instead of concatenating every endpoint id and deduplicating afterwards, which widened the attribute columns to float on every route that fell through the hot paths (#2058, chain seam; the row-pipeline pivot dtypes are a separate item).
 * GFQL: the chain specializations move into `graphistry/compute/chain_specializations/{admission,hotpaths}.py` (pandas/cuDF single-node lane, seeded typed single hop, seeded typed RETURN-destination) and `graphistry/compute/gfql/lazy/engine/polars/chain_specializations/{admission,hotpaths}.py` (polars plain single-hop branches, seeded lane, RETURN-destination), each lane next to the admission predicate the dispatcher calls (`native_fast_path_admits`, `polars_plain_single_hop_admits`, `polars_seeded_lane_admits`); `chain.py` and the polars chain only dispatch, `chain_fast_paths.py` keeps the shared seed/index helpers. No route admits or declines anything it did not before. Tests mirror the new paths and filter one shared shape corpus per route with the route's own gate; `GFQL_ROUTES_OFF=<route,...>` (test conftest) makes named hot paths decline so every existing test replays through the other routes, and `bin/test-routes-off.sh` reports the per-route divergences.
 * GFQL: the wavefront seed-rediscovery rule moved out of `hop.py` into `graphistry/compute/gfql/seed_rediscovery.py` (pandas/cuDF) and `graphistry/compute/gfql/lazy/engine/polars/seed_rediscovery.py` (polars); `undirected_rediscovered_seed_ids` (an internal helper) is gone.
+### Performance
+
+* GFQL latency: this release closes a set of point-lookup regressions found while re-measuring the LDBC SNB Interactive shapes, and adds the gates that stop them coming back. Regressions fixed: every Cypher string query on a wide pandas node table re-scanned the object columns to key the compile cache (#2029); an undirected multi-hop paid a per-edge Python loop in the seed-rediscovery rule (#2023) and a whole-frame dedup of the doubled edge frame on pandas and cuDF; the LDBC IS1 form (a seeded hop returning properties of both aliases) and the seeded single-node lookup ran the full chain with no index consulted; native op-list chains scanned the node table for a seed given on a non-binding property even with a node-property index resident, declined named patterns that the chain fast path could serve, and on polars never consulted the resident seed indexes at all (#2027, #2033; now served through the resident node-id, adjacency and node-property indexes on pandas, cuDF and polars, with the engagement visible in `gfql_explain`). Gates added: `test_gfql_latency_contract.py` (fast path served plus a bounded ratio to plain frame ops for the basic shapes on pandas, polars and cuDF), `test_hop_scaling_pin.py` (undirected 2-hop cost bounded relative to two plain joins), and, in the private benchmark repository, a point-latency sentinel on the real SF0.1 fixture with absolute sub-10 ms thresholds that runs on every release candidate before the documentation numbers are re-vendored, plus an exporter gate that fails any unexplained slowdown or new loss in the published cells. The sentinel also times native op-list twins of the same shapes with untimed receipts of the route that served them and value parity with the full path, so a fast path that stops engaging is reported rather than hidden behind a still-correct answer.
+
+### Docs
+
+- **GFQL docs navigation is split into a short start path and two hubs**: `gfql/index` now lists four Start Here pages, a Performance and Benchmarks hub (`gfql/perf/index`), a Language Reference hub (`gfql/reference/index`), and the developer specs. No page moved, so existing URLs are unchanged; the previously unlisted `gfql/loading_graph_data` page joins the reference hub.
+- **The GFQL benchmark pages state the result first and consolidate caveats**: `gfql/benchmark_filter_pagerank` (now titled as a case study and listed under Start Here) and `gfql/benchmark_graphframes` open with what the page compares and the measured outcome (GraphFrames: GFQL's best engine faster in all eight cells, CPU alone in six), keep every number unchanged, and move measurement rules into one "Method and limits" section per page. The GraphFrames page gains per-task bar charts rendered from `gfql/_static/graphframes/results.json` by the same generator and sync test as the Neo4j charts. The `bench-provenance` directive now accepts several run ids and renders one Measurement block with caveats folded in; run provenance strings name the RAPIDS base image (pyg-bench #220).
+- **The speedup case study renders GFQL arms re-measured at the 0.59.0 release commit**: the vendored artifact now carries the 2026-09-04 filter/PageRank GFQL cells (Twitter CPU 2.62 s, GPU 0.23 s; GPlus CPU 34.11 s, which selects exactly the locked Neo4j lane's node set). The GPlus GPU arm selects a different node set than the CPU arm (Jaccard 0.91), so its time renders as a diagnostic and no GPlus GPU-vs-CPU ratio is published; the Twitter ratio is 11.3x. The pandas pipeline slowdown versus the July measurement is attributed by a same-harness A/B (#2021) and the cuGraph/igraph tail difference is tracked in #2022.
+- **GFQL performance page renders the relaned four-engine q1–q9 board and the aligned SNB matrix**: the vendored pyg-bench artifact now carries the 2026-08-13 board (GFQL bound cold per timed run) with Kuzu, Memgraph, and Neo4j columns and the SNB-derived SF0.1/SF1 four-engine tables, where the databases win every point-lookup cell. `gfql/performance` drops its release-pinned heading and every hand-typed legacy figure (typed-hop fast path, index timings, the old Neo4j five-query table, the bulk engine sweep, LadybugDB) in favor of published cells, one Measurement block, and win counts derived from cells by a new `:bench-tally:` role. The bench extension now enforces `policy.max_compute_commit_drift` against the checkout (git history permitting) with per-run waivers carried in the artifact, so a board measured long before the current compute code fails the build instead of aging silently. `gfql/overview` states where GFQL wins and where the databases win, with links.
+- **GFQL docs wording and structure pass**: Start Here is now the 10-minute guide, the overview, and the speedup case study; the quick reference and Cypher syntax guide head the Language Reference hub. `gfql/indexing` and `gfql/index_adjacency` carry plain-language titles. The engines page folds its opening note boxes into prose and its "coming from" table names the concrete change and where the measurement lives (Memgraph added, PuppyGraph dropped). `gfql/about` examples 3–7 gain tested Cypher twins, example 4 now returns rows on its own sample graph, and the sample-graph block runs in the doc-example lane so later examples are checked against it. Marketing filler ("leverage", "seamless", "honest") is removed across the GFQL pages.
+- **GFQL overview states the positioning up front**: `gfql/overview` says GFQL is the only open-source in-process Cypher on dataframes and frames it against the columnar engines readers already know. An empty hidden toctree that rendered the page as a folder is gone.
 
 ## [0.59.0 - 2026-08-31]
 

agents/skills/docs-review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: docs-review
+description: Editorial policy for user-facing documentation (docs/source/**). Use when writing or reviewing prose in docs pages, docstrings that render in docs, or release notes. Plain, direct, forward-readable text; no internal process talk; no AI-writing tells.
+---
+
+# Docs editorial policy
+
+Audience: a pandas, Polars, or Cypher user who has never seen this codebase. They read once,
+forwards, and stop at the first sentence that does not pay off.
+
+## Rules (ASD-STE100 in spirit)
+
+- One idea per sentence, about 20 words, active voice, present tense.
+- Verbs over nouns: "the index reads only those neighborhoods", not "the index enables
+  neighborhood-scoped reads".
+- Say the benefit to the reader, then the mechanism, then the evidence link. Never the
+  mechanism alone.
+- Define or replace jargon on first use. Prefer the plain phrase (right column):
+
+  | avoid | write |
+  |---|---|
+  | shape (of a query) | kind of query, query pattern, workload |
+  | seeded / seed set / seeded lookup | a query that starts from a few known nodes |
+  | lane, route, fast path, hot path | (omit; say what runs faster and when) |
+  | parity, oracle | the same result on every engine |
+  | decline, typed decline | raises an error before the query runs |
+  | materialize (intermediate) | build an intermediate result |
+  | frontier | the nodes reached at this hop |
+  | point lookup | a query for one node by id |
+  | receipt, artifact, committed artifact | (omit; link the provenance section once) |
+  | attenuation, engagement | (omit) |
+  | release gate, CI, sweep, lever, step N | (omit; internal process) |
+
+- No parentheticals inside sentences. Split them into sentences or delete them.
+- No unnecessary contrast flourishes: "not X but Y", "no GPU, same results", "X — and Y".
+  State Y.
+- No mannerist titles ("The one-line speedup"). Title = what the reader gets to do
+  ("Switch engines with one keyword").
+- No footnote-style citations in body text ("[F1] Polars leads"). Put one fact inline with
+  its link, or move the block to a provenance section.
+- No competitor ammunition. Say where GFQL is good and link the full board with the
+  losses shown. Do not editorialize a competitor's strengths.
+- No internal process in user docs: release gates, CI lanes, what we refuse to publish,
+  how numbers were audited. One provenance line with a link is enough.
+- Every number comes from a vendored benchmark cell (`:bench-*:` roles). Never type a
+  measured number as a literal.
+- Keep examples and tables; cut prose. A rewrite that shortens prose by a third with no
+  loss of meaning is the normal outcome of a review.
+
+## AI-writing tells to remove
+
+- Triads for rhythm ("fast, safe, and simple"), stacked em-dash asides, "not only … but".
+- Sentences that restate the previous one with more adjectives.
+- "Deliberately", "carefully", "seamlessly", "robust", "powerful", "leverage".
+- Rhetorical questions and "so what does this mean?" transitions.
+- Claims about the writing itself ("this page is honest about losses").
+
+## Review procedure
+
+1. Read the page forwards once as the target reader. Mark every stop.
+2. For each section ask: what is the one message that is powerful to deliver? If none,
+   delete the section. If one, rewrite the section to deliver it in the fewest sentences.
+3. Apply the jargon table, then the tells list.
+4. Check every link and every `:bench-*:` role still resolves; run
+   `python -m pytest docs/test_bench_numbers.py`.
+5. Post the ReadTheDocs preview link per changed page with the sections to check.

docs/.rstcheck.cfg

@@ -22,7 +22,8 @@ ignore_roles =
     py:obj,
     py:data,
     bench,
-    bench-diag
+    bench-diag,
+    bench-tally
 
 # Ignore Sphinx-specific directives
 ignore_directives =
@@ -47,6 +48,7 @@ ignore_directives =
     include,
     graphviz,
     bench-provenance,
+    bench-board,
     bench-disclosures
 
 # Ignore common informational messages