apache · imbajin · Sep 17, 2026 · Sep 9, 2026 · Sep 17, 2026
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -60,8 +60,11 @@ For example:
 
 ## Documentation Status
 
-<!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
+Select one option and provide the documentation location when applicable.
+
+- [ ] `Doc - TODO`: required documentation is pending; complete it before merging.
+- [ ] `Doc - Done`: documentation is included here or linked below.
+- [ ] `Doc - No Need`: no user-visible documentation is affected.
 
-- [ ]  `Doc - TODO` <!-- Your PR changes impact docs and you will update later -->
-- [ ]  `Doc - Done` <!-- Related docs have been already added or updated -->
-- [ ]  `Doc - No Need` <!-- Your PR changes don't impact/need docs -->
+Documentation files in this PR or paired hugegraph-doc PR:
+<!-- For No Need, leave this blank. A follow-up issue alone does not replace required documentation. -->
diff --git a/.serena/memories/architecture_and_modules.md b/.serena/memories/architecture_and_modules.md
@@ -32,4 +32,5 @@ Distributed storage + Raft: `hg-store-core`, `hg-store-node`, `hg-store-client`,
 - **hugegraph-cluster-test**: Cluster integration tests
 
 ## Distributed Deployment (BETA)
-PD + Store + Server (3+ nodes each), all gRPC. Docker compose configs in `docker/` directory, using bridge networking (migrated from host mode).
+PD manages placement and metadata; Store owns partition data; Server serves graph queries.
+Development and HA topologies differ; see `docker/README.md` for node counts and configuration.
diff --git a/.serena/memories/code_style_and_conventions.md b/.serena/memories/code_style_and_conventions.md
@@ -24,5 +24,5 @@
 - Validate: `mvn apache-rat:check -ntp` + `mvn editorconfig:check`
 
 ## Build
-- Java 11 target, `-Xlint:unchecked`, Lombok 1.18.30 (provided/optional)
+- Java 11 target except Commons (Java 8 target); compiler/dependency versions come from module POMs.
 - Swagger: `io.swagger.core.v3:swagger-jaxrs2-jakarta` for REST API docs
diff --git a/.serena/memories/ecosystem_and_related_projects.md b/.serena/memories/ecosystem_and_related_projects.md
@@ -7,7 +7,7 @@
 |------|---------|
 | hugegraph-toolchain | Loader, Hubble (visualization), Tools CLI, Java Client |
 | hugegraph-computer | OLAP: PageRank, Connected Components, Shortest Path |
-| incubator-hugegraph-ai | Graph RAG, KG construction, NL→Gremlin/Cypher |
+| apache/hugegraph-ai | Graph RAG, KG construction, NL→Gremlin/Cypher |
 | hugegraph-doc | Docs & website (hugegraph.apache.org) |
 
 ## Data Flow
@@ -20,4 +20,5 @@ Sources → hugegraph-loader → hugegraph-server → Hubble / Computer / AI
 - Queries: Gremlin (TinkerPop 3.5.1), OpenCypher, REST API + Swagger UI
 - Storage: RocksDB (default), HStore (distributed)
 
-## Version: Server 1.7.0, TinkerPop 3.5.1, Java 11+
+## Versions
+Read Server revision from root `pom.xml` and TinkerPop from `hugegraph-server/pom.xml`.
diff --git a/.serena/memories/implementation_patterns_and_guidelines.md b/.serena/memories/implementation_patterns_and_guidelines.md
@@ -20,7 +20,7 @@
 ## gRPC Protocol
 - PD protos: `hugegraph-pd/hg-pd-grpc/src/main/proto/`
 - Store protos: `hugegraph-store/hg-store-grpc/src/main/proto/`
-- After `.proto` changes: `mvn clean compile` → `target/generated-sources/protobuf/`
+- After `.proto` changes: `mvn clean compile`; PD/Store gRPC POMs output to each module's `src/main/java/`.
 
 ## Query Languages
 - **Gremlin**: Native TinkerPop 3.5.1
@@ -36,10 +36,10 @@
 - **Backends in CI**: memory, rocksdb, hbase (matrix)
 - **Single test class**: `mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -Dtest=ClassName`
 - TinkerPop tests: only on `release-*`/`test-*` branches
-- Raft tests: only on `test*`/`raft*` branches
+- Server Raft API tests are branch-gated in `server-ci.yml`; Store raft-core tests run in normal `pd-store-ci.yml` CI.
 
 ## Docker
-- Single-node: `docker/docker-compose.yml` (bridge network, pd+store+server)
+- Standalone: `docker/docker-compose.yml` (bridge network, Server + Hubble)
 - Cluster: `docker/docker-compose-3pd-3store-3server.yml`
 - Container logs: stdout-based
 

diff --git a/.serena/memories/key_file_locations.md b/.serena/memories/key_file_locations.md
@@ -16,7 +16,7 @@
 - Tests: `hugegraph-test/src/main/java/.../` → `unit/`, `core/`, `api/`, `tinkerpop/`
 
 ## Docker
-- `docker/docker-compose.yml` — Single-node (bridge network, pd+store+server)
+- `docker/docker-compose.yml` — Standalone Server + Hubble (bridge network)
 - `docker/docker-compose-3pd-3store-3server.yml` — 3-node cluster
 - `docker/docker-compose.dev.yml` — Dev mode
 

diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md
@@ -22,5 +22,5 @@ Apache HugeGraph is a fast-speed, highly-scalable graph database supporting 10+
 - **Storage**: RocksDB (default/embedded), HStore (distributed/production), HBase (deprecated; planned for removal in 2.0)
 
 ## Version
-- Current: 1.7.0 (`${revision}` property, Maven flatten plugin)
+- Read `${revision}` from the root `pom.xml`; Maven flatten resolves it for published artifacts.
 - License: Apache License 2.0
diff --git a/.serena/memories/suggested_commands.md b/.serena/memories/suggested_commands.md
@@ -5,7 +5,7 @@
 mvn clean install -DskipTests                           # Full build
 mvn clean install -pl hugegraph-server -am -DskipTests  # Server only
 mvn clean compile -U -Dmaven.javadoc.skip=true -ntp     # Compile only
-mvn clean package -DskipTests                           # Distribution → install-dist/target/
+mvn clean package -DskipTests                           # Aggregate distribution → root target/
 ```
 
 ## Test
@@ -19,7 +19,7 @@ mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb
 # Single test class
 mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -Dtest=YourTestClass
 
-# TinkerPop compliance (release/test branches only)
+# TinkerPop compliance (can be run locally on any branch)
 mvn test -pl hugegraph-server/hugegraph-test -am -P tinkerpop-structure-test,memory
 
 # PD/Store (build struct first)
@@ -45,8 +45,9 @@ bin/enable-auth.sh                            # Enable auth
 ```
 
 ## Docker
+Create the required authentication environment first; follow `docker/README.md`.
 ```bash
-cd docker && docker compose up -d                                          # Single-node (bridge network)
+cd docker && docker compose up -d                                          # Standalone Server + Hubble (bridge network)
 cd docker && docker compose -f docker-compose-3pd-3store-3server.yml up -d # Cluster
 ```
 

diff --git a/.serena/memories/task_completion_checklist.md b/.serena/memories/task_completion_checklist.md
@@ -1,6 +1,8 @@
 # Task Completion Checklist
 
-## 1. Code Quality (MANDATORY)
+## 1. Validation scope
+Documentation-only changes: check links, paths and `git diff --check`.
+For code changes, select relevant checks below and follow root `AGENTS.md` before pushing.
 ```bash
 mvn apache-rat:check -ntp       # License headers
 mvn editorconfig:check          # Style (.editorconfig)
@@ -10,7 +12,7 @@ mvn clean compile -Dmaven.javadoc.skip=true  # Compile warnings
 
 ## 2. Testing
 - Choose backend: `memory` (fast), `rocksdb` (realistic), `hbase` (deprecated compatibility)
-- Single test: `-Dtest=ClassName` works with all profiles
+- Single-test selection: check the module test POM and confirm the requested test actually ran.
 - Bug fix → existing tests; New feature → write tests; Refactor → affected module tests
 
 ## 3. Dependencies (if adding new)
@@ -23,10 +25,13 @@ mvn clean compile -Dmaven.javadoc.skip=true  # Compile warnings
 - `server-ci.yml`: memory/rocksdb/hbase × Java 11
 - `rerun-ci.yml`: auto-retries flaky failures
 - `licence-checker.yml`: header validation
-- Raft tests: only `test*`/`raft*` branches
+- Server Raft API tests are branch-gated; Store raft-core and core tests run in normal PD/Store CI.
 - TinkerPop tests: only `release-*`/`test-*` branches
 
-## 5. Commit
+## 5. Documentation
+- Follow root `AGENTS.md`: user-visible feature/configuration/deployment changes ship with matching docs.
+
+## 6. Commit
 - NEVER commit unless explicitly asked
 - Format: `feat|fix|refactor(module): msg`
 - Include issue ID if available
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,108 +1,62 @@
 # AGENTS.md
 
-Single source of truth for AI coding agents.
-README.md covers human-facing deployment/ecosystem context; only consult it on demand.
+Repository-specific guidance; module files add local details.
 
-## Stack & Modules
+## Key relationships
 
-Apache HugeGraph — Apache TinkerPop 3 compliant graph database.
-Java 11+, Maven 3.5+. Version managed via `${revision}` (currently `1.8.0`).
+```text
+Server (hugegraph-server): graph engine + REST/Gremlin API
+  ├─ RocksDB: embedded backend
+  └─ HStore adapter → Store client → Store: partition data + Raft
 
+PD: placement + metadata; consulted by Server and Store
+Struct: shared types/codecs; separate implementations also exist in Server
+Commons: shared utilities; independent compiler and test settings
 ```
-Client (Gremlin / Cypher / REST)
-   │
-Server = hugegraph-server
-   ├─ hugegraph-api     REST, Gremlin/Cypher, auth
-   ├─ hugegraph-core    engine, schema, traversal, BackendStore interface
-   └─ Backend impls     rocksdb (default, embedded) │ hstore (distributed)
-                                                    ▼
-                           hugegraph-pd (placement) + hugegraph-store (Raft)
-```
-
-Top-level modules: `hugegraph-server` · `hugegraph-pd` · `hugegraph-store` ·
-`hugegraph-commons` (shared utils & RPC) · `hugegraph-struct` (data types; dep of PD/Store).
 
-Server submodules worth knowing: `hugegraph-core`, `hugegraph-api`,
-`hugegraph-rocksdb`, `hugegraph-hstore`, `hugegraph-test`, `hugegraph-dist`.
+## Load on demand
 
-## Code Search Anchors
-
-| Area | Path |
+| Work area | Read when working there |
 |---|---|
-| Graph engine | `hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/` |
-| REST APIs | `hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/` |
-| Backend interface | `hugegraph-server/hugegraph-core/.../backend/store/BackendStore.java` |
-| Auth | `hugegraph-server/hugegraph-api/.../api/auth/` |
-| gRPC protos | `hugegraph-{pd,store}/hg-{pd,store}-grpc/src/main/proto/` |
-
-Config roots (under each dist module's `src/assembly/static/conf/`):
-- Server — `hugegraph.properties`, `rest-server.properties`, `gremlin-server.yaml`
-- PD / Store — `application.yml`
-
-## Build
+| Graph engine, API, backends | [Server](hugegraph-server/AGENTS.md) |
+| Placement, metadata, PD client | [PD](hugegraph-pd/AGENTS.md) |
+| Distributed storage and client | [Store](hugegraph-store/AGENTS.md) |
+| Shared data types and serialization | [Struct](hugegraph-struct/AGENTS.md) |
+| Utilities and RPC | [Commons](hugegraph-commons/AGENTS.md) |
+| Container deployment | [Docker guide](docker/README.md) |
+| PR requirements | [Contribution guide](docs/CONTRIBUTING.md) |
+
+## Repository constraints
+
+- Use existing module boundaries; keep unrelated refactors out of a fix.
+- User-visible feature, configuration or deployment behavior changes must ship with matching docs.
+  Update in-repository docs in the same PR; link a paired `apache/hugegraph-doc` PR when website
+  docs are affected and coordinate both merges. A follow-up issue alone does not satisfy this rule.
+  Internal-only changes can use `Doc - No Need`.
+- Keep README as an entry point; link detailed deployment instructions instead of duplicating them.
+- Keep AGENTS.md under 100 lines where practical. Shared rules belong here, local exceptions
+  in module files. Keep key relationships, common commands and non-obvious pitfalls inline;
+  reference existing sources for versions, configuration details and lengthy procedures.
+
+## Build and validation
+
+Commands run from the repository root. Java 11+ and Maven 3.5+;
+versions come from [pom.xml](pom.xml), including `${revision}`.
 
 ```bash
-# All modules
 mvn clean install -DskipTests
-
-# Single module
 mvn clean install -pl hugegraph-server -am -DskipTests
 ```
 
-Distributed build order (for HStore-enabled dev):
-
-```bash
-mvn install -pl hugegraph-struct -am -DskipTests         # 1. shared data types
-mvn clean package -pl hugegraph-pd -am -DskipTests       # 2. placement driver
-mvn clean package -pl hugegraph-store -am -DskipTests    # 3. distributed storage
-mvn clean package -pl hugegraph-server -am -DskipTests   # 4. server
-```
-
-Runtime scripts (human-run) live in `hugegraph-server/hugegraph-dist/src/assembly/static/bin/`:
-`init-store.sh`, `start-hugegraph.sh`, `stop-hugegraph.sh`.
-
-## Testing
-
-Server tests implicitly prefix `mvn test -pl hugegraph-server/hugegraph-test -am`:
-
-| Profile | Suffix |
-|---|---|
-| Unit | `-P unit-test` |
-| Core | `-P core-test,rocksdb` (swap `rocksdb` for `memory`) |
-| API | `-P api-test,rocksdb` |
-| TinkerPop structure / process | `-P tinkerpop-{structure,process}-test,memory` |
-| Single class | `-P core-test,rocksdb -Dtest=YourTestClass` |
-
-PD / Store tests (need `hugegraph-struct` installed first):
-
-```bash
-mvn install -pl hugegraph-struct -am -DskipTests
-mvn test -pl hugegraph-pd/hg-pd-test -am
-mvn test -pl hugegraph-store/hg-store-test -am
-```
-
-Before writing new tests, check existing suites under `hugegraph-server/hugegraph-test/`.
-
-## Style & Pre-commit
-
-- Line 120, 4-space indent, LF, UTF-8, **no star imports**
-- Commit format: `feat|fix|refactor(module): msg`
-- Run before pushing:
-  ```bash
-  mvn editorconfig:format                         # enforce code style
-  mvn clean compile -Dmaven.javadoc.skip=true     # surface warnings
-  ```
-
-## Cross-module notes
-
-- `.proto` edits: `mvn clean compile` regenerates gRPC stubs under
-  `target/generated-sources/protobuf/` (output packages `*/grpc/` are excluded from Apache RAT).
-- Adding a third-party dep: update `install-dist/release-docs/{LICENSE,NOTICE,licenses/}`
-  and `install-dist/scripts/dependency/known-dependencies.txt`.
-- `hugegraph-commons` is shared by every module; `hugegraph-struct` must precede PD/Store;
-  server backends depend on `hugegraph-core`.
-
-## Additional context files
-
-`.serena/memories/` — notably `suggested_commands.md` and `task_completion_checklist.md`
-when a task needs depth beyond this file.
+For separate distributed-module builds, install `hugegraph-struct` first,
+then build PD, Store and Server. Module guidance covers tests and CI prerequisites.
+Commons tests require `-DskipCommonsTests=false`; a successful build does not imply its tests ran.
+
+- Java style: 120 columns, 4 spaces, no star imports; see [.editorconfig](.editorconfig).
+- Before pushing code: `mvn editorconfig:format`,
+  `mvn clean compile -Dmaven.javadoc.skip=true`, and relevant module tests.
+  Documentation-only changes need link/path checks and `git diff --check`.
+- PD/Store `.proto` builds generate Java into each `hg-*-grpc/src/main/java/` directory;
+  see the corresponding gRPC module POM before editing or cleaning generated sources.
+- New dependencies require updating [release LICENSE/NOTICE/licenses](install-dist/release-docs/)
+  and [dependency inventory](install-dist/scripts/dependency/known-dependencies.txt).
diff --git a/README.md b/README.md
@@ -315,15 +315,15 @@ For comprehensive documentation, visit the [HugeGraph Documentation](https://hug
 | Understand configuration | `hugegraph-dist` | `src/assembly/static/conf/` |
 | Run tests | `hugegraph-test` | Test suites with multiple profiles |
 
-For detailed architecture and development guidance, see [AGENTS.md](AGENTS.md).
+For repository constraints and module guidance, see [AGENTS.md](AGENTS.md).
 
 <details>
 <summary><b>For Contributors</b></summary>
 
 **New to HugeGraph?** Follow this path to get started:
 
 1. **Understand the Architecture**
-   - Read [AGENTS.md](AGENTS.md) for detailed module structure and development patterns
+   - Read [AGENTS.md](AGENTS.md) for key component relationships and module guidance
    - Review the [Architecture Diagram](#architecture) above
 
 2. **Set Up Your Environment**

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -125,6 +125,13 @@ Note that since GitHub requires submitting code through `username + token` (inst
 
 Go to the web page of GitHub fork repo, there would be a chance to create a Pull Request after pushing to a new branch, click the button "Compare & pull request" to do it. Then edit the description for proposed changes, which can just be copied from the commit message.
 
+User-visible feature, configuration or deployment behavior changes must ship with matching
+documentation. Include repository documentation in the same PR. When website documentation
+is affected, link a paired [hugegraph-doc](https://github.com/apache/hugegraph-doc) PR and
+coordinate both merges. A follow-up issue alone does not replace required documentation.
+In the PR template, mark pending documentation as `Doc - TODO` until it is ready;
+use `Doc - Done` with the documentation files or PR link, or `Doc - No Need` for internal-only changes.
+
 Note: please make sure the email address you used to submit the code is bound to the GitHub account. For how to bind the email address, please refer to https://github.com/settings/emails:
 <img width="1280" alt="image" src="https://user-images.githubusercontent.com/9625821/163522445-2a50a72a-dea2-434f-9868-3a0d40d0d037.png">