[imbajin]

Purpose of the PR

1. Unify Client & API Navigation:

   • Eliminate semantic duplication in the sidebar between "Clients and APIs" (/docs/clients/) and "HugeGraph Client" (/docs/quickstart/client/).
   • Group multi-language client libraries into a dedicated secondary directory (/docs/clients/client/) covering Java, Python, and Go SDKs.
   • Consolidate Java Client quickstart and comprehensive API reference into a unified, streamlined Java Client guide.
   • Maintain 100% backward compatibility with previous URLs through Hugo aliases and data/version_routes.json equivalents.

2. Graph Query Language & Cypher Integration:

   • Integrate Cypher language guides, compatibility matrix, and Neo4j migration guide into /docs/language/.
   • Update navigation and index cards to present both Gremlin and Cypher query languages side-by-side.
   • Optimize table presentation using OINK native .wide and .expand block attributes.

3. Modernize Typography & Layout (OINK Native Components):

   • Convert procedural workflows and multi-step setups into OINK {.steps}.
   • Restructure multi-environment and multi-command guides into {tab="..."} tabbed code blocks.
   • Use structured cards ({.cards} / {.td-cards-list}) for parallel components and navigation hubs.
   • Adopt standard GitHub alerts (> [!NOTE], > [!TIP], > [!WARNING]).

4. 90-Day Upstream Audit & Gap Filling (5 Core Repositories):

   • Conducted systematic audit of recent 90-day commits across apache/hugegraph, apache/hugegraph-toolchain, apache/hugegraph-ai, apache/hugegraph-computer, and apache/hugegraph-doc.
   • Added comprehensive audit inventory in scripts/audit-90d-commits-inventory.md cataloging 37 user-facing features and changes.
   • Documented Server REST API additions: Schema Clone (POST /graphs/{graph}/clone), Same Neighbors Batch Traversal (POST /traversers/sameneighbors), Cypher query parameterization & 200/400 envelope split (cypher.md), GraphSpace quota & storage capacity (graphspace.md).
   • Documented PD & Storage additions: Raft topology monitoring, node offline cycle (hugegraph-pd.md), RocksDB provider configuration (config-option.md).
   • Documented HugeGraph-AI additions: New standalone bilingual Python Client SDK guide (hugegraph-llm-sdk.md), Python >= 3.12 baseline, and review_options schema in /graph/extract.
   • Documented Toolchain & Computing additions: Vermeer integration in Hubble (vermeer.token_file), Computer Java 17 runtime baseline, Vermeer health/telemetry endpoints, and custom plugin SPI OptionHolder class reference.

What is included

• content/{cn,en}/docs/clients/ & content/{cn,en}/docs/clients/client/: Unified client navigation, consolidated Java client guide, relocated Python/Go client guides with redirect aliases.
• content/{cn,en}/docs/quickstart/hugegraph-ai/hugegraph-llm-sdk.md: New bilingual SDK guide covering graph extraction, schema generation, and query pipeline APIs.
• content/{cn,en}/docs/language/: Cypher and Gremlin guides with improved table readability and accurate compatibility matrix.
• scripts/audit-90d-commits-inventory.md: Full 90-day commit audit inventory across 5 core HugeGraph repositories.
• data/docs_nav.json & data/version_routes.json: Synchronized 5-group navigation tree and multi-version compatibility mappings.
• content/{cn,en}/docs/guides/architectural/custom-plugin.md: Aligned SPI OptionHolder implementation details.

Validation

• bash dist/validate-links.sh: Passed with 0 broken links.
• python3 -m unittest discover -s scripts/: All 290 tests passed.
• SITE_ROOT=public npm --prefix tests/e2e test -- search-ranking.spec.js: All 35 Playwright search ranking tests passed.
• ./scripts/hugo.sh build: Strict Hugo bilingual build verified cleanly with 668 pages rendered.

[imbajin]

P2: Please preserve the historical SDK navigation when introducing the new client grouping.

At the reviewed revision, the new /docs/clients/client parent does not exist in the pinned historical route sets. docs_nav_page_for_routes() has no SDK relocation fallback, and adapt() drops an unresolved parent before visiting its children. The old quickstart-client subtree is also removed.

CI attempt 1 confirms historical navigation mismatches: 1.0 has 56 pages instead of 59; 1.3 has 65 instead of 68; 1.5 has 72 instead of 77; 1.7 has 80 instead of 85. Please adapt the grouping to the existing historical SDK routes, preserve logical cross-version equivalents, and validate all supported versions before updating expected statistics. Simply accepting the smaller counts would leave the navigation loss unaddressed.

Separately, the latest-version validation fails because cn/index.html links to the missing /cn/docs/quickstart/client/hugegraph-client/ target. The new Java page already declares that alias; please check the generated alias/locale and homepage-link handling rather than merely adding another declaration. The exact alias-generation cause is not established here.

Evidence: independent static inspection and the three official build-job logs for this head/run/attempt; no independent local Hugo build or runtime Cypher validation.

[bitflicker64]

Inline findings for the R1 review summary, which is posted separately.

[bitflicker64]

Review summary: R1 (FULL)

Reviewed: head 7db47aaa against base 7d1737b5, all 49 files.

Verdict: not ready to merge yet. Two problems break existing routes: historical SDK navigation is lost, and the old CN client URLs return 404. The Cypher pages also contain inaccurate information about clause support and authentication.

Score: 3.9 / 10. This is the mean of all 4 reviewers.

Reviewer	Raw	Adjusted	Deductions
Reviewer A (model not reported)	5.0	5.0	2 Important, 2 Minor
Reviewer B (Claude Opus 5.5)	3.5	3.5	2 Important, 5 Minor
Reviewer C (Gemini 3.8 Flash)	7.0	7.0	1 Important, 2 Minor
Reviewer D (Gemini 4 Argon)	0.0	0.0	1 Critical, 2 Important, 2 Minor

Important:

• Historical SDK navigation is lost for 1.0 to 1.7, as already reported in this review. Reviewer A reached the same conclusion independently.
• The CN aliases get a double /cn prefix, so the old CN client URLs return 404. This is the cause of the cn/index.html failure in CI. Reviewer D rated this Critical.
• Switching from the old Java quickstart to latest falls back to the docs home page.
• The "Unsupported Features" list includes OPTIONAL MATCH, WITH and UNWIND. Reviewers rated this Important or Minor.
• The Cypher pages now say no Authorization header is needed when auth is off, but the server returns 401.

Minor: EN section numbering and old anchors, wrong sample-dataset description, Cypher error and Content-Type wording, removed "since 1.8.0" caveats.

[Uncertain / needs confirmation]: language/hugegraph-example.md and the new hugegraph-cypher.md both use weight: 2. The sidebar order comes from data/docs_nav.json, so only Hugo's own page ordering (such as prev/next links) may be affected.

Checks: dist/validate-links.sh and the scripts unit tests pass. A strict Hugo 0.168.0 build succeeds but generates the CN redirects under /cn/cn/.

[bitflicker64]

Inline finding added to the R1 review summary from a late reviewer.

[imbajin]

A source-level clarification on the authentication finding: in the checked Server revision, CypherAPI.client(), !manager.requireAuthentication() returns getAnonymousClient() before reading the Authorization header. The Basic/Bearer checks and missing-header 401 apply to the authentication-enabled branch, not unconditionally.

Please retain that distinction rather than restoring an unconditional header requirement based on this finding. This is an independent static control-flow check, not a live Cypher success test or a claim about older released Server versions. It does not change the separate navigation/alias findings or CI failures.

[imbajin]

Two small documentation follow-ups at the current revision:

• EN migration guide, line 46: #known-limitations no longer matches the renamed Limitations heading. Please use #limitations or retain the old explicit anchor.
• Line 104: absence from the compatibility matrix is not evidence that a clause will fail validation. Please describe uncovered constructs as unverified and reserve “unsupported” for established limitations.

The earlier historical-navigation, CN-alias and Java version-switch issues are addressed in this revision by independent static inspection and bounded navigation/route models. Those checks are not a full Hugo/browser run or CI/RC acceptance. These remaining items are nonblocking documentation corrections; they do not reopen the earlier navigation finding.

[bitflicker64]

Inline findings for the R2 review summary, which is posted separately.

[bitflicker64]

Review summary: R2 (FULL)

Reviewed: head 01b8113f against base 8f74072b (master after the #499 merge), all 50 files. Previous round: R1 summary, at head 7db47aaa.

Verdict: no blocking issues found. Every R1 finding is fixed; the status of each is posted in its original thread. Three Minor items remain.

Score: 9.6 / 10. This is the mean of all 4 reviewers.

Reviewer	Raw	Adjusted	Deductions
Reviewer A (model not reported)	9.5	9.5	1 Minor
Reviewer B (Claude Opus 5.5)	9.0	9.0	2 Minor
Reviewer C (Gemini 3.8 Flash)	8.0	10.0	1 Important, removed as disproved (see below)
Reviewer D (Gemini 4 Argon)	10.0	10.0	none

Minor:

• Version notes removed from the restful-api index, auth and graphs pages
• The "rather than a JSON object" note on raw-text POST
• Old deep-section anchors not kept on the merged Java page

R1 correction: the R1 finding about the Cypher Authorization header was wrong. Master has allowed anonymous Cypher queries when auth is disabled since apache/hugegraph#3366; details are in the R1 thread. The current text is accurate. The R1 summary is left unchanged as the historical record of that round. In R2, Reviewer C repeated the old auth and URL-safe Base64 claim. That deduction is removed: on master, CypherAPI#client returns the anonymous client when auth is disabled, and the decoder is Base64.getDecoder().

Checks: dist/validate-links.sh passes, and a strict Hugo 0.168.0 build passes. Navigation built from the latest, 1.7, 1.5, 1.3 and 1.0 snapshots matches the expected stats. versioning.py build and validate pass for latest and for 1.7 (against release-1.7.0). No browser check was done.

[bitflicker64]

Blocking: no. Summary: The earlier navigation, alias, route and Cypher findings are fixed at 01b8113, and what remains is documentation corrections. The three Minor comments from the last round still apply, and the CN graphs.md note no longer says GET /graphspaces is PD-only.

[bitflicker64]

Blocking: no. Summary: The open comments from the 01b8113 round are fixed at ba98daf: version notes, the Cypher body wording, the deep client anchors and the CN PD-only note. The guides move keeps aliases and version routes, and two new Minor documentation errors remain.

[imbajin]

Thanks for the review! In the latest push (8faa8816e):

1. Addressed reviewer findings:

   • Fixed Loader section 3.4 link anchor to #34-execute-command-import in EN and #34-执行命令导入 in CN (hugegraph-loader.md).
   • Corrected SPI interface naming from OptionSpace to OptionHolder in EN and CN (custom-plugin.md).

2. Completed 90-day upstream audit & feature alignment across 5 core repositories:

   • Added comprehensive audit inventory in scripts/audit-90d-commits-inventory.md (covering 37 user-facing features from hugegraph, hugegraph-toolchain, hugegraph-ai, hugegraph-computer, and hugegraph-doc).
   • Added standalone bilingual HugeGraph-LLM Python SDK documentation (hugegraph-llm-sdk.md) and updated Python >= 3.12 baseline and /graph/extract options.
   • Documented Schema Clone API (POST /graphs/{graph}/clone) and Same Neighbors batch traversal endpoint (POST /traversers/sameneighbors).
   • Documented Cypher parameterization support, 200/400 envelope separation, and anonymous client behavior.
   • Documented GraphSpace quota/capacity constraints and PD Raft node lifecycle/monitoring metrics.
   • Documented Vermeer cluster telemetry endpoints and Hubble vermeer.token_file configuration.

3. Validation:

   • bash dist/validate-links.sh: 0 broken links.
   • python3 -m unittest discover -s scripts/: 290/290 passed.
   • search-ranking.spec.js: 35/35 Playwright tests passed.
   • ./scripts/hugo.sh build: 668 pages rendered cleanly with zero errors.

[imbajin]

Incremental review of the current documentation update (2026-11-01). Three documentation contract/validation issues below need correction. Evidence is independent static review plus a bounded Python signature-binding probe, not live SDK, cluster, full Hugo or RC acceptance. The current CI run 41339231303 attempt 1 failed in Build group 0, job 124945894618, step 11; its logs were unavailable to this review, so the static route finding is not asserted as the observed CI root cause. No score is carried over from earlier heads.

[bitflicker64]

Inline findings for the R3 review summary, which is posted separately.

[bitflicker64]

Review summary: R3 (FULL)

Reviewed: head 8faa8816 against base 8f74072b, all 108 files. Previous round: R2 summary, at head 01b8113f.

Verdict: not ready to merge yet. Navigation, aliases and versioning are clean, and the R2 items are fixed or mostly fixed. The newly added feature content, however, has several factual errors against current upstream code. A reader who copies these configs or examples will hit failures.

Score: 4.4 / 10. This is the mean of all 4 reviewers. Reviewer B hit the floor of 0. Reviewer C's 9.5 does not include the confirmed Important items below; for example, it reported rocksdb.provider as correct, but this was checked against RocksDBOptions and it is not. A high average therefore does not mean the PR is ready.

Reviewer	Raw	Adjusted	Deductions
Reviewer A (model not reported)	0.5	0.5	4 Important, 3 Minor
Reviewer B (Claude Opus 5.5)	0.0	0.0	7 Important, 7 Minor (5 provisional)
Reviewer C (model not reported)	9.5	9.5	1 Minor
Reviewer D (Gemini 4 Argon)	7.0	7.5	1 Important, 1 Minor (1 Minor removed as already present in base)

Important (all newly added text; EN and CN):

• Hubble Vermeer port 8888 should be 6688
• Hubble Vermeer algorithm list
• LLM SDK is not on PyPI
• LLM SDK examples use non-existent arguments
• rocksdb.provider default and allowed values
• PD drain check names the wrong config key
• The new LLM SDK page is missing from version_routes.json and docs_nav.json, so versioning.py validate --version latest fails
• Vermeer cluster-snapshot schema

Minor:

• Batch same-neighbors response fields
• PD cd glob
• Committed internal audit log. Reviewers were split on this one.
• Remaining legacy Java anchors

[Uncertain / needs confirmation]: reported by one reviewer and not yet confirmed:

• the MCP page requires Python ≥ 3.12, while hugegraph-mcp@1.7.1 supports ≥ 3.10;
• the Computer page requires JDK 17 but pins 1.7.0;
• the chunk stage list in hugegraph-ai/rest-api.md is incomplete;
• the Python client claims LlamaIndex integration.

Checks: dist/validate-links.sh passes, and a strict Hugo 0.168.0 build passes. Navigation built from the release-1.7.0 snapshot matches the expected stats. A full artifact build passes validate for 1.7 and fails for latest because of the missing SDK route.

[bitflicker64]

Inline finding added to the R3 review summary from a late reviewer.

[bitflicker64]

Inline findings for the R4 review summary, which is posted separately.

[bitflicker64]

Review summary: R4 (DELTA)

Reviewed: the changes from 8faa8816 to 723899ec (8 commits, 23 files), plus a re-check of every open R3 item at the new head. Base is 8f74072b. Previous round: R3 summary.

Verdict: no blocking issues found. All eight Important items from R3 are fixed and were re-checked against current upstream code, and so are the audit-file and traverser items. Each R3 thread has a status reply. Seven Minor items remain.

Score: 8.8 / 10. This is the mean of all 4 reviewers.

Reviewer	Raw	Adjusted	Deductions
Reviewer A (model not reported)	8.5	8.5	3 Minor
Reviewer B (Claude Opus 5.5)	7.0	7.0	6 Minor
Reviewer C (model not reported)	9.5	9.5	1 Minor
Reviewer D (Gemini 4 Argon)	10.0	10.0	none

Minor:

• Vermeer example gRPC ports (new in this update)
• children_by_url misses the SDK page
• Legacy 1.x/5.x anchors on the merged Java page
• MCP Python requirement vs pinned 1.7.1
• Computer page lost the JDK note for 1.7.0
• Incomplete chunk stage list
• LlamaIndex integration claim

Checks: dist/validate-links.sh passes, and a strict Hugo 0.168.0 build passes. versioning.py build and validate pass for latest (100 pages) and for 1.7 (85 pages), and both match the expected stats.

[imbajin]

Thanks @bitflicker64 for the detailed R4 review! All 7 Minor findings have been addressed in 0d2775def:

1. Vermeer example gRPC ports: Corrected master gRPC peer to 127.0.0.1:6689 and worker gRPC peer to 127.0.0.1:6789 (EN & CN hugegraph-vermeer.md).
2. Docs navigation precomputed maps: Synchronized data/docs_nav.json so that children_by_url["/docs/quickstart/hugegraph-ai/"] and active_path_by_url["/docs/quickstart/hugegraph-ai/hugegraph-llm-sdk/"] include the new SDK page for direct preview/build compatibility.
3. Legacy Java client anchors: Added explicit heading anchors ({#1-hugegraph-client}, {#5-simple-example}, {#11-builder-options}, {#12-operation-entries} in EN; and CN equivalents) on the consolidated Java client page (hugegraph-client.md).
4. MCP Python version requirement: Clarified Python >= 3.10 requirement for the pinned 1.7.1 package vs >= 3.12 for master / 1.8.0+ (EN & CN hugegraph-mcp.md).
5. Computer JDK requirement: Re-stated JDK 11 requirement for the pinned 1.7.0 release alongside JDK 17+ requirement for 1.8.0+/master (EN & CN hugegraph-computer.md).
6. AI chunk stage enum: Completed the execution stages list with prepare, extract, validate, review, and repair (EN & CN rest-api.md).
7. Python client description: Reworded client index cards to describe actual pyhugegraph capabilities and native HugeGraph-LLM/ML integrations (EN & CN clients/client/_index.md).

All link validations (validate-links.sh), unittests (290/290 passed), and Hugo strict builds pass cleanly.