apache · imbajin · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026
diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml
@@ -28,6 +28,7 @@ on:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || (inputs.operation == 'staging-next' && 'asf-staging-oink' || 'asf-site') }}
+  # A newer commit supersedes previous work for the same PR or publish target.
   cancel-in-progress: true
 
 env:
@@ -231,7 +232,7 @@ jobs:
           restore-keys: ${{ runner.os }}-hugo-${{ env.HUGO_VERSION }}-${{ matrix.version.id }}-
       - name: Verify pinned OINK module
         run: |
-          python3 scripts/oink_module.py
+          python3 scripts/update_oink.py --check-baseline
       - name: Build isolated version artifact
         env:
           OINK_PYTHON: python3
@@ -256,11 +257,14 @@ jobs:
           if-no-files-found: error
           overwrite: true
 
+  # Assembly and browser checks are serial; reuse one runner and its local output.
   aggregate:
     needs: [prepare, build]
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 35
     permissions: { contents: read }
+    env:
+      HUGO_CACHEDIR: /tmp/hugo-cache-${{ github.run_id }}-${{ github.run_attempt }}-aggregate
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -309,18 +313,6 @@ jobs:
           if-no-files-found: error
           overwrite: true
 
-  e2e:
-    needs: [prepare, aggregate]
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    permissions: { contents: read }
-    env:
-      HUGO_CACHEDIR: /tmp/hugo-cache-${{ github.run_id }}-${{ github.run_attempt }}-e2e
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          ref: ${{ needs.prepare.outputs.source_sha }}
-          persist-credentials: false
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: "24"
@@ -335,10 +327,6 @@ jobs:
         with:
           hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
-        with:
-          name: hugegraph-site-${{ needs.prepare.outputs.artifact_prefix }}-${{ github.run_id }}
-          path: public-site
       - name: Install Chromium test workspace
         working-directory: tests/e2e
         run: |
@@ -358,12 +346,12 @@ jobs:
       - name: Run blocking Chromium contracts
         working-directory: tests/e2e
         env:
-          SITE_ROOT: ${{ github.workspace }}/public-site
+          SITE_ROOT: ${{ runner.temp }}/public-site
           AI_SITE_ROOT: ${{ runner.temp }}/ai-site
           EXPECTED_VERSIONS: ${{ needs.prepare.outputs.selection }}
         run: npm run test:ci
       - name: Upload E2E report
-        if: always()
+        if: ${{ !cancelled() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: playwright-report-${{ github.run_id }}-${{ github.run_attempt }}
@@ -402,7 +390,7 @@ jobs:
           npx playwright install --with-deps chromium
           npm run test:visual
       - name: Upload advisory visual evidence
-        if: always()
+        if: ${{ !cancelled() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: visual-evidence-${{ github.run_id }}-${{ github.run_attempt }}
@@ -412,8 +400,8 @@ jobs:
 
   # Required check name in .asf.yaml. It gates artifacts without write access.
   deploy:
-    if: always()
-    needs: [prepare, build, aggregate, e2e]
+    if: ${{ !cancelled() }}
+    needs: [prepare, build, aggregate]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions: { contents: read }
@@ -423,12 +411,10 @@ jobs:
           PREPARE_RESULT: ${{ needs.prepare.result }}
           BUILD_RESULT: ${{ needs.build.result }}
           AGGREGATE_RESULT: ${{ needs.aggregate.result }}
-          E2E_RESULT: ${{ needs.e2e.result }}
         run: |
           test "$PREPARE_RESULT" = success
           test "$BUILD_RESULT" = success
           test "$AGGREGATE_RESULT" = success
-          test "$E2E_RESULT" = success
 
   publish:
     if: needs.prepare.outputs.publish_branch != ''

diff --git a/AGENTS.md b/AGENTS.md
@@ -1,110 +1,38 @@
-# AGENTS.md
-
-This file provides guidance to AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.) when working with code in this repository.
-
-## Project Overview
-
-Apache HugeGraph documentation website built with Hugo static site generator and the Docsy theme. The site is bilingual (Chinese/English) and covers the complete HugeGraph graph database ecosystem.
-
-## Development Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Start development server (auto-reload enabled)
-hugo server
-
-# Build production site (output to ./public)
-hugo --minify
-
-# Clean build
-rm -rf public/
-
-# Production build with garbage collection
-HUGO_ENV="production" hugo --gc
-
-# Custom server configuration
-hugo server -b http://127.0.0.1 -p 80 --bind=0.0.0.0
-```
-
-## Prerequisites
-
-- **Hugo Extended** v0.95.0 recommended (v0.102.3 in CI) - must be the "extended" version for SASS/SCSS support
-- **Node.js** v16+ and npm
-- Download Hugo from: https://github.com/gohugoio/hugo/releases
-
-## Architecture
-
-```
-content/
-├── cn/          # Chinese documentation (default language)
-│   ├── docs/    # Main documentation
-│   ├── blog/    # Blog posts
-│   ├── community/
-│   └── about/
-└── en/          # English documentation (parallel structure)
-
-themes/docsy/    # Docsy theme (submodule)
-layouts/         # Custom template overrides
-assets/          # Processed assets (SCSS, images)
-static/          # Static files served directly
-config.toml      # Main site configuration
-```
-
-### Content Structure
-
-Documentation sections in `content/{cn,en}/docs/`:
-- `quickstart/` - Getting started guides for HugeGraph components
-- `config/` - Configuration documentation
-- `clients/` - Client API documentation (Gremlin, RESTful)
-- `guides/` - User guides and tutorials
-- `performance/` - Benchmarks and optimization
-- `language/` - Query language docs
-- `contribution-guidelines/` - Contributing guides
-- `changelog/` - Release notes
-- `download/` - Download instructions
-
-## Key Configuration Files
-
-- `config.toml` - Site-wide settings, language config, menu structure, version (currently 0.13)
-- `package.json` - Node dependencies for CSS processing (postcss, autoprefixer, mermaid)
-- `.editorconfig` - UTF-8, LF line endings, spaces for indentation
-
-## Working with Content
-
-When editing documentation:
-1. Maintain parallel structure between `content/cn/` and `content/en/`
-2. Use Markdown with Hugo front matter (title, weight, description)
-3. For bilingual changes, update both Chinese and English versions
-4. Include mermaid diagrams where appropriate (mermaid.js is available)
-
-## Deployment
-
-- **CI/CD**: GitHub Actions (`.github/workflows/hugo.yml`)
-- **Trigger**: Push to `master` branch or pull requests
-- **Build**: `npm i && hugo --minify` with Node v16 and Hugo v0.102.3 extended
-- **Deploy**: Publishes to `asf-site` branch (GitHub Pages)
-- **PR Requirements**: Include screenshots showing before/after changes
-
-## HugeGraph Ecosystem Context
-
-This documentation covers:
-- **HugeGraph-Server** - Core graph database with REST API
-- **HugeGraph-Store** - Distributed storage engine
-- **HugeGraph-PD** - Placement Driver for metadata
-- **Toolchain** - Client, Loader, Hubble (web UI), Tools
-- **HugeGraph-Computer** - Distributed OLAP graph processing
-- **HugeGraph-AI** - GNN, LLM/RAG components
-
-## Troubleshooting
-
-**"TOCSS: failed to transform scss/main.scss"**
-- Install Hugo Extended (not standard Hugo)
-
-**Theme/module not found**
-- Run: `git submodule update --init --recursive`
-
-**CI build fails but works locally**
-- Match Hugo version (v0.102.3) and Node.js (v16)
-- Verify npm dependencies are installed
+# HugeGraph documentation
+
+Bilingual Hugo site using OINK as a pinned Go module. English routes live under
+`/docs/`, Chinese routes under `/cn/docs/`; historical releases share the current
+site shell.
+
+## Task entry points
+
+- Preview or build: `scripts/hugo.sh server` / `scripts/hugo.sh build`.
+- Content and contribution checks: [contribution.md](contribution.md).
+- OINK upgrades, customization boundaries and recovery:
+  [scripts/oink-upgrade.md](scripts/oink-upgrade.md).
+- Version assembly and publishing: `scripts/versioning.py` and
+  `.github/workflows/hugo.yml`; release selection comes from `versions.json`.
+- Browser regression: `tests/e2e/package.json` and its Playwright configuration.
+  Node dependencies are for tests, not the Hugo site build.
+
+Read the entry relevant to the task; small content edits do not require the full
+upgrade or deployment workflow. Use `go.mod` / `go.sum` and CI for pinned versions.
+
+## Project constraints
+
+- Keep English and Chinese documentation aligned when a change applies to both.
+- Preserve public routes, historical-version navigation and language switching.
+- Keep HugeGraph branding and behavior in site configuration, data, hooks and
+  public OINK APIs. Do not edit the module cache or vendor a theme fork.
+- Record necessary upstream template overrides in the upgrade inventory; when
+  upstream changes them, reconcile the customization with the new implementation.
+- AI resources load only after explicit user consent; disabled AI must make no
+  third-party AI requests.
+- Validate behavior affected by the change. Theme/runtime changes require strict
+  builds and browser checks; visual/navigation changes also need before/after
+  screenshots. A rendered site alone does not prove interaction compatibility.
+- Independent work may run in parallel. Review the final combined diff independently
+  for changes affecting runtime behavior or multiple components; local content
+  edits can use self-review.
+- Local builds and disposable tests may run without repeated confirmation. Remote
+  writes and publishing follow the user's explicit task scope.
diff --git a/NOTICE b/NOTICE
@@ -6,5 +6,5 @@ The Apache Software Foundation (http://www.apache.org/).
 
 The initial codebase was donated to the ASF by HugeGraph Authors, copyright 2017-2021.
 
-This product includes OINK v1.0.0 (https://github.com/pgsty/oink),
+This product includes OINK (https://github.com/pgsty/oink),
 Copyright 2026 PGSTY contributors, licensed under the Apache License 2.0.
diff --git a/README.md b/README.md
@@ -32,7 +32,7 @@ scripts/hugo.sh server
 
 Open http://localhost:1313 to preview.
 
-The module graph must resolve `github.com/pgsty/oink@v1.0.0`. For a production-equivalent check, run the strict build command shown below.
+The module graph must resolve the OINK version pinned in `go.mod`; verify it with `python3 scripts/oink_module.py`. For a production-equivalent check, run the strict build command shown below.
 
 ## Repository Structure
 
@@ -51,7 +51,7 @@ hugegraph-doc/
 │   └── en/                     # 🇺🇸 English documentation (mirrors cn/ structure)
 │
 ├── data/                       # 🧭 Landing-page and footer data
-├── i18n/zh-CN.yaml             # 🌐 OINK interface strings for the /cn/ locale
+├── i18n/zh-CN.yaml             # 🌐 HugeGraph labels for the /cn/ locale
 ├── assets/                     # 🖼️  Project brand assets
 ├── layouts/                    # 📐 Hugo template overrides
 ├── static/                     # 📁 Static files
@@ -79,6 +79,7 @@ hugegraph-doc/
 ### Detailed Guide
 
 See [contribution.md](./contribution.md) for the pinned toolchain, strict build, OINK customization, and translation rules.
+For theme updates, compatibility review and rollback, use the [OINK upgrade SOP](./scripts/oink-upgrade.md).
 
 ## Commands
 
@@ -87,6 +88,7 @@ See [contribution.md](./contribution.md) for the pinned toolchain, strict build,
 | `scripts/hugo.sh server` | Start the manifest-aware dev server (hot reload) |
 | `scripts/hugo.sh build` | Strict, production-equivalent build to `./public/` |
 | `scripts/hugo.sh server -p 8080` | Start the dev server on a custom port |
+| `scripts/update-oink.sh v1.1.0` | Update the theme and run compatibility checks (see the SOP) |
 
 ---
 
@@ -116,7 +118,7 @@ scripts/hugo.sh server
 
 打开 http://localhost:1313 预览网站。
 
-模块图必须解析为 `github.com/pgsty/oink@v1.0.0`。需要执行与生产一致的检查时，请运行下方的严格构建命令。
+模块图必须解析为 `go.mod` 固定的 OINK 版本，可运行 `python3 scripts/oink_module.py` 校验。需要执行与生产一致的检查时，请运行下方的严格构建命令。
 
 ### 仓库结构
 
@@ -135,7 +137,7 @@ hugegraph-doc/
 │   └── en/                     # 🇺🇸 英文文档（与 cn/ 结构一致）
 │
 ├── data/                       # 🧭 首页与页尾数据
-├── i18n/zh-CN.yaml             # 🌐 /cn/ 语言的 OINK 界面文案
+├── i18n/zh-CN.yaml             # 🌐 /cn/ 语言的 HugeGraph 专属文案
 ├── assets/                     # 🖼️  项目品牌资源
 ├── layouts/                    # 📐 Hugo 模板覆盖
 ├── static/                     # 📁 静态文件
@@ -163,6 +165,7 @@ hugegraph-doc/
 #### 详细指南
 
 查看 [contribution.md](./contribution.md) 了解固定工具链、严格构建、OINK 定制和翻译要求。
+主题升级、兼容适配和回退请按 [OINK 升级 SOP](./scripts/oink-upgrade.md) 操作。
 
 ### 常用命令
 
@@ -171,6 +174,7 @@ hugegraph-doc/
 | `scripts/hugo.sh server` | 启动读取版本清单的开发服务器（支持热重载） |
 | `scripts/hugo.sh build` | 严格构建与生产等价的站点到 `./public/` |
 | `scripts/hugo.sh server -p 8080` | 在指定端口启动开发服务器 |
+| `scripts/update-oink.sh v1.1.0` | 更新主题并执行兼容检查（详见升级 SOP） |
 
 ---