[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.

[bitflicker64]

Minor: #34-execute-the-import matches no heading; section 3.4 renders as #34-execute-command-import, so this step link goes nowhere. Point it at #34-execute-command-import, and the CN step at #34-执行命令导入 instead of #34-执行导入.

[bitflicker64]

Minor: OptionSpace is the final registry class behind registerOptions(), not something a plugin implements; OptionSpace.register requires a subclass of OptionHolder, as this page's RocksDBOptions extends OptionHolder example shows. Name OptionHolder here and in the CN step.

[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.

[imbajin]

P2: The new extraction examples do not match the SDK signature. At the audited AI main version, extract_graph (and aextract_graph) accepts texts, not text or text_or_chunks, and has no **kwargs. Thus this example, the bounded-repair example, and the concurrency example fail during argument binding before any model call; both locales and the API table need the same correction. Please use texts= (or a positional argument) and add an example/signature smoke check. I verified the exact source and a bounded signature-binding probe, not a live SDK/provider run. Source: https://github.com/apache/hugegraph-ai/blob/f85393030be2605899e26165b3c0873c368e2425/hugegraph-llm-sdk/src/hugegraph_llm_sdk/api.py#L117-L128

[imbajin]

P2: The new EN and CN SDK pages are ordinary published pages, but neither logical ID appears in data/version_routes.json, and data/docs_nav.json has no SDK node. canonical_docs_pages inventories these pages, while aggregate validation rejects canonical pages missing from the map. The AI landing-page link alone does not register either route. Please add the latest routes with appropriate historical nulls, add the authored navigation entry, and regenerate derived navigation evidence. This is a static validation-path finding; I have not run the full Hugo/aggregate build or attributed the current CI result to it. Sources:

hugegraph-doc/scripts/versioning.py

Lines 2461 to 2490 in 8faa881

	def canonical_docs_pages(root: pathlib.Path, version: str) -> dict[str, str]:
	"""Inventory canonical Docs pages, excluding redirect aliases and print views."""
	pages: dict[str, str] = {}
	for language, docs_root in (
	("en", root / "docs"),
	("cn", root / "cn/docs"),
	):
	if not docs_root.is_dir():
	fail(f"route-map Docs root is missing for {version}: {docs_root}")
	for path in sorted(docs_root.rglob("index.html")):
	document = DocumentParser()
	document.feed(path.read_text(encoding="utf-8"))
	if refresh_target(document):
	continue
	relative = path.parent.relative_to(docs_root).as_posix()
	relative = "" if relative == "." else relative
	logical_relative = normalize_logical_docs_route(version, relative)
	logical_id = f"{language}:{logical_relative}"
	target = (
	("cn/docs/" if language == "cn" else "docs/")
	+ (relative.rstrip("/") + "/" if relative else "")
	)
	previous = pages.get(logical_id)
	if previous is not None and previous != target:
	fail(
	f"ambiguous canonical route for {version} {logical_id}: "
	f"{previous} and {target}"
	)
	pages[logical_id] = target
	return pages

and

hugegraph-doc/scripts/versioning.py

Lines 4619 to 4624 in 8faa881

	extras = sorted(set(actual).difference(route_map["pages"]))
	if extras:
	fail(
	f"canonical Docs pages are absent from route-map for "
	f"{version}: {extras}"
	)

[imbajin]

P2: Please align the bilingual cluster snapshot example with the actual wire schema. metric_status is an object with availability, observed_at and optional reason, not the string ok; availability values are AVAILABLE/UNAVAILABLE/UNSUPPORTED. The worker checks are connection_ready, load_stream_ready, compute_stream_ready, and superstep_stream_ready, not the keys shown here. A monitoring client copied from this example would parse the wrong shape/keys. Please derive the example from the existing snapshot fixture while keeping metric availability separate from readiness. This is source-contract verification, not a live cluster test. Source: https://github.com/apache/hugegraph-computer/blob/3a8d988c55ac0c6187455914639c4413f0b304fc/vermeer/apps/master/services/http_cluster.go#L35-L54 and #L184-L198.