This is an automated email from the ASF dual-hosted git repository. imbajin pushed a commit to branch handoff/oink-site-improvements in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git
commit bba8d83864a351a24fa6737d7f91ed33a16a8287 Author: dark <[email protected]> AuthorDate: Sat Sep 5 23:19:30 2026 +0800 docs(goal): add portable OINK handoff - expose only the active OINK goal-task directory - record exact remote branches, CI state, and resume order - retain portable design and browser evidence --- .gitignore | 4 +- .goal-task/oink-site-improvements/design.md | 220 ++++++++ .../evidence/ask-ai-visual-directions.md | 41 ++ .../evidence/ask-ai-visual-directions.png | Bin 0 -> 1244536 bytes .../evidence/browser/cn-community-mobile-dark.png | Bin 0 -> 364601 bytes .../evidence/browser/cn-docs-desktop-dark.png | Bin 0 -> 361399 bytes .../evidence/browser/cn-search-mobile-dark.png | Bin 0 -> 368142 bytes .../evidence/browser/cn-sidebar-mobile-dark.png | Bin 0 -> 373961 bytes .../browser/en-community-desktop-light.png | Bin 0 -> 597410 bytes .../evidence/browser/en-docs-desktop-light.png | Bin 0 -> 384735 bytes .../evidence/browser/en-docs-mobile-light.png | Bin 0 -> 301023 bytes .../evidence/browser/en-search-desktop-light.png | Bin 0 -> 531488 bytes .../evidence/browser/en-sidebar-desktop-light.png | Bin 0 -> 789664 bytes .goal-task/oink-site-improvements/handoff.md | 94 ++++ .goal-task/oink-site-improvements/lessons.md | 224 ++++++++ .goal-task/oink-site-improvements/pr-a-body.md | 72 +++ .goal-task/oink-site-improvements/pr-b-body.md | 42 ++ .goal-task/oink-site-improvements/state.md | 568 +++++++++++++++++++++ .goal-task/oink-site-improvements/todo.md | 168 ++++++ 19 files changed, 1432 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index cc2d3a994..c80b4d30f 100644 --- a/.gitignore +++ b/.gitignore @@ -34,4 +34,6 @@ GEMINI.md .aider* .gemini/ WARP.md -/.goal-task +/.goal-task/* +!/.goal-task/oink-site-improvements/ +!/.goal-task/oink-site-improvements/** diff --git a/.goal-task/oink-site-improvements/design.md b/.goal-task/oink-site-improvements/design.md new file mode 100644 index 000000000..4a40294ac --- /dev/null +++ b/.goal-task/oink-site-improvements/design.md @@ -0,0 +1,220 @@ +# HugeGraph OINK 网站改进规划 + +## 1. 目标与优先级 + +聚焦 master 上的 OINK 网站；Docusaurus 预览站只参考 Ask AI、Community 等产品设计，不读取或迁移其实现与构建方式。交互以普通鼠标、触屏和快捷键用户为主，无障碍检查仅作为防回归护栏。 + +| 优先级 | 评分 | 已确认事项 | +|---|---:|---| +| P0 | 10.0 | 修复侧栏分层、隐藏焦点、移动抽屉和导航交互 | +| P0 | 9.8 | 增加 1.3/1.0，重构五版本 CI 与预发发布 | +| P0 | 9.6 | OINK 原生搜索内融合可选 Kapa Ask AI | +| P0 | 9.5 | Community 增加 ASF PMC/Committers 头像墙 | +| P1 | 9.0 | 统一 OINK 主题 token，补强 summary 搜索元数据 | +| P1 | 8.6 | LLMSFULL、Backlinks、图片缩放、复制链接、社交预览图和内容组件试点 | +| P2 | 8.0 | ASF-aware 数据驱动下载页，作为第二阶段 | +| Deferred | ≤6.5 | 全文索引及其他低收益或高外部依赖能力 | + +## 2. 第一阶段实现 + +### 2.1 OINK Shell、导航与侧栏 + +- 将 `#532fc9` 迁移为 `ui.theme_color`，导航、侧栏、焦点、选中态、搜索和 Ask AI 共用 OINK 明暗色 token，删除可替代的硬编码颜色。 +- 顶部保留 `Documentation / Download / Blog / Community`： + - Documentation 下拉改为“开始、组件、开发、运维、参考”五组图标入口。 + - 仅保留右侧 branch 图标作为版本选择器，消除重复版本菜单。 + - 采用 [OINK 官方站](https://oink.pgsty.com/)原生手感：hover/focus 展开、移出延迟关闭、点击标题进入文档首页、↓ 进入菜单、Esc 关闭。 +- 侧栏收起后完全离开布局和交互树，删除左缘 hover 浮层；只能点击显式按钮恢复。 +- 默认只展开当前页面祖先；用户手动展开的节点可持久化。 +- 折叠状态全站共享；节点状态使用 `oink.sidebar.v1.<version>.<locale>` 隔离，只保存稳定节点 ID，active path 始终优先，失效 ID 自动清理；localStorage 不可用时退化为当前祖先展开。 +- 移动抽屉关闭时隔离内部交互、恢复触发按钮、解除滚动锁；同时修复汉堡按钮低对比度。 + +### 2.2 本地搜索与 Ask AI + +本地搜索继续采用 `summary`，不会因 AI 服务替换、延迟或失效。 + +- 为 latest 中英文 12 组核心入口补充克制的 `search_keywords/search_boost/search_exclude`： + - Introduction、Server、HStore、PD、Computer、Loader、Hubble、Clients、REST、Config、Authentication、Download。 + - 用固定中英文查询集验证目标页进入前列，禁止全站机械堆词。 +- 明确区分“无匹配结果”和“索引加载失败”；失败态提供本地重试。 +- 有非空普通查询时，在本地结果末尾追加 Ask AI 行；空查询、命令模式和 choice 模式不显示。 +- 保留全站浮动 launcher；移动端使用紧凑尺寸和 safe-area，不遮挡正文。 +- launcher 打开空白 AI 会话；搜索结果中的 Ask AI 自动提交当前查询。 +- 只向 Kapa 发送裁剪后的查询字符串，不发送当前 URL、页面内容、版本信息或本地结果。 +- 历史版本入口和面板明确标注“回答基于 latest 文档”；第三方服务说明只在 AI 面板中显示。 +- Kapa 脚本仅在用户点击后加载；5 秒未完成脚本加载或 render 即进入非阻塞错误态，保留入口和本地结果并允许重试。迟到响应不得自动弹窗。 +- launcher 与搜索行共用 `idle/loading/ready/error` 状态机，防止双击、重复脚本和并发打开。 +- Kapa 不接管 `Cmd/Ctrl+K`；关闭 AI 后焦点返回真实触发入口。 + +配置契约： + +```yaml +params: + ai_search: + enabled: true + provider: kapa + website_id: 0b277570-4740-451e-96fa-1e4ac1ac5e88 + source_groups: + en: "<reviewed-latest-en-source-group-id>" + cn: "<reviewed-latest-cn-source-group-id>" +``` + +- `enabled=false` 时不输出 launcher、适配脚本或任何 Kapa 请求。 +- 开启时 provider、website ID 和两种语言 source group 缺一即构建失败；这些均为公开浏览器标识，不使用 secret。 +- bundle URL、5 秒超时和隐私策略固定在适配器中，不允许配置任意脚本地址。 +- 固定关闭 Kapa launcher、搜索模式、Command-K、consent、匿名 Cookie 和 fingerprint；保留现有 hCaptcha 防滥用。 +- Kapa 面板按 OINK token 完整覆盖字体、颜色、边框、圆角和浅/深色，禁止使用旧版红粉 UI。实现参考 [Kapa Functions](https://docs.kapa.ai/integrations/website-widget/javascript-api/functions)、[Theming](https://docs.kapa.ai/integrations/website-widget/configuration/theming) 和 [User Tracking](https://docs.kapa.ai/integrations/website-widget/features/user-tracking)。 +- 不复制 OINK 的完整 command palette 脚本；先利用现有 manual-init 与 model/registry 注入实现薄适配，并向 OINK 上游提交通用 `registerExtension({ placement: "search-tail", rows, activate })` API。上游发布后删除本站包装层。 +- CSP 仅允许 staging 实测确认的 Kapa、hCaptcha 和必要代理精确主机，不使用通配域名；生成 HTML 仍不得静态嵌入第三方 active resource。 + +### 2.3 Kapa 知识库 + +- latest EN/CN 文档根启用 OINK `LLMSFULL`，分别生成 `/docs/llms-full.txt` 和 `/cn/docs/llms-full.txt`。 +- Kapa 只摄取这两个 LLMSFULL 文件，不同时爬 HTML，避免重复引用。 +- 英文页面只启用 EN source group，中文页面只启用 CN source group。 +- Kapa 后台必须完成： + - 排除历史和旧 Docusaurus global sources。 + - 配置生产、OINK staging 两个允许域名。 + - 完成首次抓取并核对来源时间。 +- 初始 corpus、source group 与 CSP 未通过 staging 验证前保持 AI 关闭；通过后同一配置在 staging 和 production 启用，不做长期分阶段开关。 + +### 2.4 五版本与路由 + +版本菜单固定为： + +```text +latest / 1.7 / 1.5 / 1.3 / 1.0 +``` + +- 跳过 1.2；中英文使用相同短标签和顺序。 +- 历史内容分别取自 `release-1.7.0`、`release-1.5.0`、`release-1.3.0`、`release-1.0.0`。 +- 配置只展示分支名；每次运行开始时仍解析一次 SHA 并在该次任务中固定，避免矩阵任务读取不同提交。 +- 以 `versions.json` 为版本、顺序、ref、发布路径的单一真源，其他菜单和校验数据由它派生。 +- 增加版本化 route-map： + - 1.3/1.0 在构建 overlay 中迁移到当前五组信息架构。 + - 旧扁平 URL 生成静态 alias/redirect，canonical 指向迁移后的同版本路径。 + - 版本切换按逻辑页面 ID 查找等价页；成功时保留 query/hash，目标不存在时跳至目标版本文档根并丢弃无效 query/hash，同时显示一次说明。 + - 1.0 中文确实缺失的页面不补译、不展示英文伪中文页；语言切换回到该版本中文根。 + - 仅在真实等价双语页面间输出 hreflang。 +- 1.7/1.5/1.3/1.0 输出 `noindex,follow` 并从 sitemap 排除；保留自 canonical、直达 URL、归档提示和切换 latest 的入口。 + +### 2.5 Community PMC/Committers + +结合 [Issue #468](https://github.com/apache/hugegraph-doc/issues/468)，在“参与社区”之后、成熟度 CTA 之前加入 Project members： + +- 角色权威来源： + - [committee-info.json](https://whimsy.apache.org/public/committee-info.json) 交叉校验 Chair/PMC。 + - [public_ldap_projects.json](https://whimsy.apache.org/public/public_ldap_projects.json) 提供 owners/members。 + - [public_ldap_people.json](https://whimsy.apache.org/public/public_ldap_people.json) 提供公开姓名。 +- `PMC = owners`；`Committers = members - owners`，禁止重复。Chair 第一，其余按 ASF 公开姓名 Unicode casefold 排序。 +- 中英文共用 `data/community/roster.json`；人工审核的 ASF ID→GitHub 映射放在 `data/community/github-map.json`，记录 numeric GitHub user ID，禁止按姓名、邮箱或提交记录猜账号。 +- 页面仅显示： + - 已映射：本地头像和 `@GitHub ID`，整卡链接 GitHub。 + - 未映射：姓名首字母和 ASF ID，链接 ASF phonebook。 + - ASF 姓名只用于排序和非视觉链接名称。 +- 复用 OINK Contributors token/class，但通过 site-local partial 直接读取嵌套数据；不依赖原生 shortcode 对嵌套路径的支持。 +- 固定 5/3/2 列：桌面 ≥1200px、平板 768–1199px、手机 <768px。 +- 头像使用同源 128×128 WebP、剥离元数据、懒加载；initials 先渲染，图片失败时无需 JavaScript 即可回退。 +- HTML、Print 和 Markdown 输出必须包含相同角色集合、顺序及 profile 链接。 + +提供： + +```bash +python3 scripts/community_roster.py refresh +python3 scripts/community_roster.py validate --warn-after-days 90 +``` + +- `refresh` 仅由维护者本地运行，生成普通 PR；不增加定时任务、机器人提交或直推。 +- 候选头像使用内容寻址文件名：先安装并验证新头像，最后原子替换 roster，再清理孤立旧头像；任何失败保持 last-good bundle。 +- `validate` 完全离线，检查 schema、集合、唯一 Chair、排序、映射闭集、账号/user ID 唯一性、头像 MIME/尺寸/hash 和渲染产物。 +- 90 天依据成功抓取的 `retrieved_at` 判断，只输出 Python/Actions warning，不进入 Hugo warning；未来日期或结构错误阻断构建。 + +### 2.6 其他已采纳 OINK 能力 + +- latest 文档启用 Backlinks，默认显示 5 条，超过后“查看全部”。 +- Docs 与 Blog 在五个版本中启用按需图片缩放。 +- Blog 页尾只提供“复制链接”，不增加社交平台跳转。 +- 使用现有 HugeGraph 品牌资产生成一张经人工审阅的 1200×630 默认社交预览图，为 Docs、Community 和 Blog 提供 fallback。 +- 仅在以下三组 latest 双语页面试点 OINK 原生内容组件： + - Server Quickstart：步骤、命令 filename/wrap/collapse。 + - Config Guide：长配置文件名、折叠与复制。 + - REST Vertex：字段锚点、宽表和请求/响应代码块。 +- 不机械改写其他页面或任何历史版本。 + +## 3. CI/CD 与交付并行 + +### 3.1 事件模型 + +| 事件 | 构建 | 发布 | +|---|---|---| +| PR | 五版本、production origin | 不发布 | +| master push | 五版本、production origin | 完整发布 `asf-site` | +| dispatch `staging-next/latest` | 指定 ASF 分支的 latest | 发布 `asf-staging-oink`；历史菜单指向 production | +| dispatch `staging-next/full` | 候选 latest + 四个历史版本 | 完整发布 `asf-staging-oink` | +| dispatch `production-history-refresh` | master shell + 五版本 | 完整发布 `asf-site` | + +- dispatch 仅能从 master 工作流启动；候选只接受 ASF 仓库普通分支，拒绝 fork、tag、裸 SHA 和输出分支。 +- staging 与 production 分别要求固定确认词；origin、profile 和目标分支全部由枚举映射，不接受自由文本。 +- 默认权限 `contents: read`；只有发布 job 使用 `contents: write`。发布 job 不 checkout 或执行候选分支代码，只下载本次 run/attempt 的明确 artifact。 +- 不新增 GitHub Environment；依靠最小权限、可信 ref、确认词、目标硬编码、新鲜度检查和 ASF `whoami`。 +- 保留 required check 名称 `deploy`；它只检查 prepare/build/aggregate/E2E 成功，不持有写权限。 +- 移除 `version × site` 笛卡尔矩阵： + - PR/master/full staging 最多 5 个并行版本构建。 + - 默认 latest staging 只运行 1 个构建。 +- 不缓存历史最终 artifact；保留现有 Go/Hugo 编译缓存。 +- resolved manifest/可发布 aggregate/E2E 报告保留 7 天，中间版本与 PR aggregate 保留 1 天。 +- 超时：prepare 10 分钟、单版本 build 20、aggregate 15、Chromium E2E 20、visual 15、deploy gate 5、publish 10。 + +### 3.2 PR 分组 + +采用两条并行第一阶段加一个第二阶段： + +1. **PR-A：OINK 核心平台** + - Shell、导航、侧栏、主题 token、搜索错误态、Ask AI、LLMSFULL、Backlinks、图片缩放、复制链接、社交卡片。 + - 五版本、route-map、CI/CD、Node/Playwright/Chromium 与发布安全。 + - 因共享 `hugo.yaml`、布局、样式、CSP、测试基座和 workflow，这些强依赖内容合入同一 PR；内部可按 UI/AI、versioning/CI、E2E 三个文件所有权 lane 并行开发。 + +2. **PR-B：Community 与内容体验** + - PMC/Committers 数据链路、独立 scoped 样式和三种输出。 + - 12 组搜索元数据、3 组双语内容组件试点。 + - 不修改 PR-A 所有的共享配置、shell 样式或 workflow，可与 PR-A 完全并行。 + +3. **PR-C：ASF 下载页第二阶段** + - 在第一阶段稳定后，把中英文下载事实收敛到单一数据源。 + - 复用 OINK 下载/checksum UI，明确支持 ASF mirror、正式 source artifact、ASC 和 SHA512；不得把 GitHub 自动 source archive 表述为 ASF 正式发行物。 + +### 3.3 Issue 与上游归档 + +- [Issue #467](https://github.com/apache/hugegraph-doc/issues/467)： + - 先追加三套 Ask AI 视觉方案对比、选择结论和“旧红粉 UI 禁止复用”说明。 + - staging 验证后再追加最终浅/深色、桌面/移动截图和验证结论。 +- PR-B 使用 `Closes #468`。 +- 另建全文搜索 Issue，记录 summary 现状、content 模式约 233–243 KiB gzip/语言/版本的估算及性能预算；本轮不实现。 +- 向 OINK 上游分别提交通用 palette extension 和侧栏交互修复；上游工作不阻塞本站交付。 + +## 4. 测试与验收 + +- 保留现有 Python/链接/产物验证；补齐五版本顺序、1.2 缺席、route-map、aliases、noindex/sitemap、canonical/hreflang、1.0 语言缺页和 staging 跨 origin 菜单合同。 +- Node 24 只用于 `tests/e2e/`；提交锁文件，并在 `.gitignore` 中仅放行该目录的 lockfile。Hugo 生产构建不执行 npm。 +- Chromium 阻断测试： + - latest 中英文完整覆盖搜索、导航、侧栏、版本切换、Community 和 AI mock。 + - 四个历史版本中英文覆盖菜单、关键路由、归档、noindex、AI latest 提示及键盘冒烟。 + - AI 覆盖禁用零请求、结果尾 CTA、点击前零第三方请求、精确 query/locale、500、超时、CSP、迟到响应、双击和重试。 + - Community 覆盖 1440/900/390/320px 的 5/3/2 列、明暗色、长账号、缺 GitHub mapping、空 Committers、HTML/Print/Markdown 一致性。 +- axe WCAG 2.2 AA、隐藏侧栏零可聚焦元素、焦点恢复及颜色对比只作为回归护栏。 +- 视觉回归永久 advisory，不进入 `deploy` gate；固定导航、搜索、侧栏、Community 的桌面/移动和浅/深色状态，并要求 PR 提供 before → after 截图。 +- 部署后真实 Kapa smoke 只验证 bundle、CSP、render 和面板可打开，不提交问题；失败仅告警，不回滚或阻止原生站点发布。 +- 发布验收要求： + - production 与 staging 原生搜索在 Kapa 故障时完整可用。 + - 所有外部请求只在用户点击 Ask AI 后出现。 + - 五版本 URL、旧链接和语言切换无 404。 + - Community 页面无访客侧 GitHub/Whimsy 请求。 + - PR-A 与 PR-B 合并后运行一次完整五版本集成构建再发布。 + +## 5. 明确延期与默认假设 + +- 延期：全文本地索引、反馈、OpenAPI/Redoc、Giscus、analytics、Authors/Series/taxonomy、Custom commands、Translation notice、Reading time、PlantUML、Draw.io、Markmap、Asciinema、KaTeX、ECharts、PDF/EPUB、PWA、导航自动隐藏、Blog 视图切换、GitHub stars 及其他展示型 Landing。 +- Ask AI 是可选增强，任何外部故障均不得改变本地搜索结果、CI 核心结论或网站可发布性。 +- 历史版本只保留原始事实，不补译、不修饰为当前行为。 +- Community 只展示当前 ASF 官方角色，不按仓库贡献次数、组织成员或公司归属推断身份。 +- 所有新界面沿用当前 OINK/HugeGraph 视觉系统，不复刻 Docusaurus 旧 UI。 diff --git a/.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.md b/.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.md new file mode 100644 index 000000000..8383a1052 --- /dev/null +++ b/.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.md @@ -0,0 +1,41 @@ +# Ask AI Visual Directions + +- Method: built-in `image_gen` +- Asset: + `evidence/ask-ai-visual-directions.png` +- Dimensions: 1717×916 PNG +- SHA-256: + `68a97ffa93941608fa6d112e77331e464df59a824b8073ebf1c5543a472c98c2` + +## Directions + +1. Search Tail — append one Ask AI action after native results for a non-empty + ordinary query. +2. Floating Launcher — keep a global compact launcher that opens the AI modal + without submitting a query. +3. Side Panel — reserve a persistent right-side assistant surface. + +## Selection + +Use Search Tail and Floating Launcher as two entrypoints into one shared modal +and state machine. Do not adopt the persistent Side Panel because it competes +with the document TOC and reduces content width. Native summary results remain +the primary surface in every state. + +The old red/pink Docusaurus treatment is explicitly excluded. The selected +surface uses the OINK/HugeGraph purple token in light and dark modes. + +## Generation prompt + +```text +Use case: ui-mockup +Asset type: design-review comparison board for a documentation website +Primary request: create one polished landscape comparison board showing three clearly separated Ask AI interface directions for the Apache HugeGraph OINK documentation site. +Scene/backdrop: clean off-white product-design review canvas with a restrained header and three equal desktop UI panels. +Subject: Panel A shows an AI action appended as the final row of native documentation search results; Panel B shows a compact floating Ask AI launcher opening a centered modal; Panel C shows a right-side assistant panel beside documentation content. Each panel should visibly preserve native local search as the primary interface. +Style/medium: realistic shippable web product UI mockup, crisp and restrained, not concept art. +Composition/framing: 16:9 landscape, three equal columns, consistent browser chrome, strong comparison hierarchy, generous whitespace. +Color palette: OINK/HugeGraph purple #532FC9 with neutral white, charcoal, soft lavender, and a credible dark-mode inset; strictly no red or pink legacy UI. +Text (verbatim): "HugeGraph", "A · Search Tail", "B · Floating Launcher", "C · Side Panel", "Search documentation", "Ask AI", "Native results stay available". +Constraints: render the listed text exactly once where appropriate; preserve accessibility-minded contrast; use modest borders and 10–12px rounding; no gradients, no glassmorphism, no decorative blobs, no unrelated logos, no watermark, no red, no pink, no extra marketing copy. +``` diff --git a/.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.png b/.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.png new file mode 100644 index 000000000..bf63d6e3d Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/cn-community-mobile-dark.png b/.goal-task/oink-site-improvements/evidence/browser/cn-community-mobile-dark.png new file mode 100644 index 000000000..d73d3d50c Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/cn-community-mobile-dark.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/cn-docs-desktop-dark.png b/.goal-task/oink-site-improvements/evidence/browser/cn-docs-desktop-dark.png new file mode 100644 index 000000000..7a5f5d853 Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/cn-docs-desktop-dark.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/cn-search-mobile-dark.png b/.goal-task/oink-site-improvements/evidence/browser/cn-search-mobile-dark.png new file mode 100644 index 000000000..070f6aeab Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/cn-search-mobile-dark.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/cn-sidebar-mobile-dark.png b/.goal-task/oink-site-improvements/evidence/browser/cn-sidebar-mobile-dark.png new file mode 100644 index 000000000..3f5240e33 Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/cn-sidebar-mobile-dark.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/en-community-desktop-light.png b/.goal-task/oink-site-improvements/evidence/browser/en-community-desktop-light.png new file mode 100644 index 000000000..01c44b95a Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/en-community-desktop-light.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/en-docs-desktop-light.png b/.goal-task/oink-site-improvements/evidence/browser/en-docs-desktop-light.png new file mode 100644 index 000000000..31ceff1a1 Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/en-docs-desktop-light.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/en-docs-mobile-light.png b/.goal-task/oink-site-improvements/evidence/browser/en-docs-mobile-light.png new file mode 100644 index 000000000..1e9856db1 Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/en-docs-mobile-light.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/en-search-desktop-light.png b/.goal-task/oink-site-improvements/evidence/browser/en-search-desktop-light.png new file mode 100644 index 000000000..93fb8de98 Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/en-search-desktop-light.png differ diff --git a/.goal-task/oink-site-improvements/evidence/browser/en-sidebar-desktop-light.png b/.goal-task/oink-site-improvements/evidence/browser/en-sidebar-desktop-light.png new file mode 100644 index 000000000..655b16ccb Binary files /dev/null and b/.goal-task/oink-site-improvements/evidence/browser/en-sidebar-desktop-light.png differ diff --git a/.goal-task/oink-site-improvements/handoff.md b/.goal-task/oink-site-improvements/handoff.md new file mode 100644 index 000000000..ab82ee18a --- /dev/null +++ b/.goal-task/oink-site-improvements/handoff.md @@ -0,0 +1,94 @@ +# OINK Site Improvements — Cross-host Handoff + +This file is the portable entrypoint for continuing the OINK site-improvement +goal on another host. Read files in this order: + +1. `design.md` — authoritative product, interface, release, and acceptance + requirements. +2. `state.md` — execution contract, exact checkpoints, decisions, and gates. +3. `todo.md` — current work queue, dependencies, waits, and deferrals. +4. `lessons.md` — failure-derived constraints that must not regress. +5. `pr-a-body.md` and `pr-b-body.md` — prepared GitHub descriptions. +6. `evidence/` — retained design and browser screenshots. + +## Remote checkpoint + +- Repository: `https://github.com/apache/hugegraph-doc.git` +- Baseline `master`: `d88167dd797efafea50cec59909d57849703fde5` +- PR-A branch: `feat/oink-core-platform` +- PR-A exact head: `25f3e8c3f7982cbf1d08c4bda572e9da9add79eb` +- PR-A: <https://github.com/apache/hugegraph-doc/pull/472> +- PR-A CI run: <https://github.com/apache/hugegraph-doc/actions/runs/33934549197> + — all jobs passed; required human review is still pending. +- PR-B branch: `feat/oink-community-content` +- PR-B exact head: `bb270838626165ad2c98c11150dde39f4eb113c9` +- PR-B has no PR yet. Create it with `Closes #468` only after rechecking the + current PR-A/base state. +- Local integration checkpoint: + `81092317458740eeaf9da8b289cb0ea7f226aaf2`. Its tree was verified + byte-identical to the union of the two pushed branch heads and contains no + unique unpushed implementation. + +All remote revisions and GitHub states are time-sensitive. Refresh them before +any mutation: + +```bash +git fetch origin --prune +git ls-remote origin \ + refs/heads/master \ + refs/heads/feat/oink-core-platform \ + refs/heads/feat/oink-community-content +gh pr view 472 --repo apache/hugegraph-doc \ + --json state,isDraft,headRefOid,mergeStateStatus,reviewDecision,statusCheckRollup,url +gh pr list --repo apache/hugegraph-doc \ + --head feat/oink-community-content --state all +``` + +## New-host bootstrap + +The destination host needs: + +- an `apache/hugegraph-doc` clone with `origin` pointing to the Apache + repository; +- GitHub authentication capable of reading CI and, before writes, confirmed + Apache branch/PR permission; +- repository submodules and the Node/Hugo/Python/Chromium dependencies used by + the current source; +- Kapa login only when the reviewed staging LLMSFULL corpus is reachable. + +Suggested worktrees: + +```bash +git worktree add ../hgdoc-oink-pra origin/feat/oink-core-platform +git worktree add ../hgdoc-oink-prb origin/feat/oink-community-content +``` + +Recreate the integration worktree from refreshed remote heads instead of +copying the source-host worktree. Preserve PR-A and PR-B ownership boundaries +defined in `state.md`. + +## First continuation action + +1. Recheck PR #472 exact-head CI and required review. +2. Merge PR-A only when branch protection permits it, with no override. +3. Refresh `origin/master`. +4. Create PR-B from the already-pushed branch with `Closes #468`. +5. Continue independent staging/Kapa preparation while review is pending. +6. Begin PR-C only after the first-phase stability gate in `design.md` is met. + +The final integrated broad review already reached the user-approved three-round +cap and finished 3/3 clear. Do not start another broad review cycle. Only a new, +reproducible release-blocking Critical may receive a narrowly scoped fourth or +fifth round. + +## Source-host-only evidence + +Absolute paths under `/Users/zhu/...` and `/private/tmp/...` in `state.md` are +historical source-host evidence locations. They are not portable and must not be +treated as existing on the destination host. The committed screenshots under +`evidence/`, exact pushed commits, GitHub CI, and a fresh destination-host +validation are the portable evidence. + +No credential values are stored in this directory. The Kapa integration ID is a +public browser identifier; authenticated browser sessions and cookies are not +portable and must be re-established on the destination host if needed. diff --git a/.goal-task/oink-site-improvements/lessons.md b/.goal-task/oink-site-improvements/lessons.md new file mode 100644 index 000000000..0155cdb8f --- /dev/null +++ b/.goal-task/oink-site-improvements/lessons.md @@ -0,0 +1,224 @@ +# OINK Site Improvements — Reusable Lessons + +## Bound review-fix convergence + +Use at most three broad review-fix rounds for one milestone. A fourth or fifth +round is reserved for a reproducible release-blocking Critical and must be +narrowly scoped to that finding. Record remaining lower-severity work instead +of repeatedly invalidating an otherwise complete matrix; keep only the affected +gate open and continue independent lanes. + +## Parse browser request syntax, then validate emitted targets + +Regex-only URL scanning missed CSS escapes, quoted URLs with spaces, +`image-set()`, SVG IRIs, duplicate HTML attributes, and list-valued image +attributes. A publication gate should tokenize each browser request surface, +apply one scheme/authority policy, and resolve same-origin resources against +the emitted artifact so a safe-looking but missing target cannot pass. + +When a theme embeds `data:` control images but the site forbids rendered data +URLs, externalize the complete theme variable set and test historical overlay +copying. A successful latest build does not prove version artifacts contain the +same shared static resources. + +## Canonicalize both sides of destructive path checks + +- Symptom: the versioning output-cleanup regression test deleted two isolated + worktrees created below `/tmp`, even though the test expected repository-root + cleanup to be rejected. +- Root cause: on macOS, `/tmp` resolves to `/private/tmp`. The candidate output + path was canonicalized while the repository root used for the safety + comparison was not, so equal paths appeared different. +- Evidence: the first run removed the versioning worktree; a later full-suite + run independently removed the Community worktree after its focused tests and + Hugo build had passed. Both branch refs survived, but uncommitted files did + not. +- Partial fix: commit `f1bffd0827d217ad17eecf5ba00ace793ecf3ff3` + canonicalizes the current repository boundary and rejects its root, + ancestors, and descendants. Its focused regression passes, but a third + deletion of a different parallel worktree proves that current-checkout + protection alone does not establish cross-worktree safety. +- Complete guard: commit `178f300c59cebb3ea4b9c135162108a24aeab6ef` + enumerates every registered Git worktree, rejects equal/ancestor/descendant + relationships, detects `.git` markers for prunable or unregistered + checkouts, and fails closed when enumeration is unavailable. Its regression + first failed against the old implementation, then passed after the fix; a + live registered `/tmp` sibling was also rejected with deletion mocked. +- Prevention: before any recursive cleanup, resolve both the protected + boundary and candidate path, then test equality and both ancestor + directions. Include a platform alias case such as `/tmp` versus + `/private/tmp`, enumerate Git worktree boundaries when multiple checkouts + share one repository, and do not run broad cleanup tests until the + cross-worktree case is proven. + +## Checkpoint isolated parallel work before broad validators + +- Symptom: Community implementation that had already passed eight focused + tests, offline roster validation, and a Hugo build was lost when a later + unrelated full-suite validator removed its worktree. +- Cause: a broad validation surface exercised destructive code outside that + lane's ownership before the lane had made a recoverable checkpoint. +- Prevention: after each focused green batch in an isolated worktree, create a + scoped local commit before running broad cross-subsystem validation. Broad + validators remain mandatory, but they run after destructive-path guards and + from a location whose recovery boundary is understood. +- Additional evidence: the first reviewer-fix batch passed 16 focused tests but + was still lost before its checkpoint when the `/tmp` worktree disappeared a + third time. High-risk parallel work now uses a worktree under + `/Users/zhu/.codex/worktrees/` until the cross-worktree cleanup cause is + proven and fixed. + +## Isolate Hugo caches when debugging failed resource pipelines + +- Symptom: after a Sass compilation error, the next Hugo build waited with zero + CPU instead of reporting the next error. +- Evidence: a process sample showed Hugo goroutines waiting; rerunning the same + source with a fresh `HUGO_CACHEDIR` immediately reported the next unsupported + Sass expression, and the final isolated-cache build completed. +- Prevention: parallel worktrees and failure diagnosis use distinct Hugo cache + directories. Treat a post-failure cache wait separately from the source error + and do not infer that the template itself is deadlocked. + +## Preserve browser CSS functions through the repository Sass compiler + +- Symptom: Node UI contracts passed, but Hugo rejected CSS Level 4 + `rgb(r g b / a)` and tried to numerically evaluate `min()` containing + viewport units. +- Root cause: the current Sass transformer parses those functions before the + browser can evaluate them. +- Fix: use compatible `rgba(r, g, b, a)` colors and quote/unquote browser-owned + `min()`, `max()`, `env()`, and nested `calc()` expressions. +- Prevention: every style batch must pass the actual Hugo production build; + JavaScript or textual contract tests are insufficient compilation evidence. + +## Propagate release-scope inputs through every validation boundary + +- Symptom: a latest-only staging artifact validated immediately after build, + but aggregate revalidation would have interpreted historical selector URLs + without the production historical origin. +- Root cause: `historical_origin` reached build and direct validation but was + dropped by the aggregate CLI and workflow step. +- Fix: make the aggregate parser, artifact revalidation namespace, and workflow + environment/command carry the same value; validate both the production + five-version aggregate and a staging latest-only aggregate. +- Prevention: treat build, upload, download, aggregate, revalidation, and + publish as one parameter-propagation chain. A contract input is complete only + when the final consumer receives it and a workflow test proves the wiring. + +## Match browser fixtures to the contract under test + +- Symptom: latest UI, search, AI, and accessibility checks passed against a + direct Hugo build, while all aggregate/version-history checks failed. +- Root cause: the browser suite was pointed at a latest-only site, which cannot + contain aggregate metadata, archived routes, aliases, or the materialized + five-version selector. +- Prevention: run latest behavior against a direct fixture only when isolated + evidence is useful; run the full blocking suite against the exact + five-version aggregate. Classify fixture-shape failures separately from + product regressions, then rerun with the correct artifact before reporting. + +## Use fallback when a Playwright fault injector must preserve remapping + +- Symptom: integrated search retry made two requests but never rendered a + result; the same behavior had passed in PR-A alone. +- Root cause: the test-specific route aborted the first hashed index request + and used `route.continue()` for the second. That bypassed the shared handler + which remaps production-origin URLs to the local aggregate. PR-A passed only + because its hash happened to exist on production; the PR-B-integrated hash + correctly returned 404 there. +- Fix: use `route.fallback()` after the injected failure so the shared artifact + handler fulfills the retry from the local aggregate. +- Prevention: fault-injection routes should terminate only the intended + failure attempt. Successful attempts must delegate through the same fixture + routing chain used by the rest of the suite, so tests never depend on live + deployment hashes. + +## Validate version switching as a logical-page contract + +- Symptom: the five-version order, version roots, builds, and broad browser + checks were green, but switching from a deep documentation page still sent + users to the target version's Docs root. +- Root cause: root-level version metadata proved that each release existed but + did not encode whether the current logical page had an equivalent in each + target release. +- Fix: generate a deterministic route map from all five canonical inventories, + materialize page-specific selector options for every rendered artifact, and + use one Hugo partial for desktop, mobile, and Palette entry points. Preserve + query/hash only for true equivalents; otherwise use the matching locale Docs + root plus a one-shot fallback sentinel and notice. +- Prevention: validate exact forward, missing/null, and reverse equality + between the route map and every version's canonical inventory. Browser tests + must cover equivalent and missing EN/CN pages through all selector surfaces; + version ordering and root-URL assertions alone do not prove page semantics. + +## Keep manifest-derived behavior in every supported entry point + +- Symptom: CI artifacts had five route-aware versions, while the documented + direct `hugo server` and strict-build commands rendered no configured + versions. After adding a manifest-aware wrapper, native anchors became + correct but Palette still consumed root-only action-manifest options. +- Root cause: configuration, native links, and action manifests were produced + at different layers. Fixing only the command or visible anchors did not make + the render-time action contract equivalent to the postprocessed CI artifact. +- Prevention: every documented build/serve entry point must derive from the + same manifest and must prove both visible anchors and embedded action + manifests on a deep page. A live-reload server test must exercise Palette, + because build-after-processing evidence cannot prove development-server + behavior. + +## Test every publication-origin mode independently + +- Symptom: production and latest-only staging passed, but full staging would + fail when an archived version lacked a latest-shared page. +- Root cause: the missing shared-route rewrite hard-coded the production + origin. That happened to be correct for production and latest-only staging + history, but contradicted full staging where both current and historical + versions share the staging origin. +- Prevention: test production full, staging full, and staging latest as three + distinct origin matrices. Shared-route fallback follows the current artifact + origin; only historical selector destinations use `historical_origin`. + +## Model renamed-page equivalence separately from canonical identity + +- Symptom: historical readme-to-readme switching was fixed, but latest + `introduction` still could not reach older `introduction/readme` pages. +- Root cause: some versions contain both a section landing and a readme while + older versions contain only the readme. Collapsing both canonical pages into + one ID loses information; keeping them unrelated loses a valid migration. +- Prevention: keep the canonical inventory one-to-one and record explicit, + disjoint, locale-matched equivalence groups. Resolve an exact target first; + only a unique alternate may count as equivalent. Alias edges must terminate + at a canonical page in the same artifact before authorizing a cross-version + target. + +## Use dedicated contracts for corpus provenance and social images + +- Symptom: LLMSFULL existence checks accepted mixed-locale or non-canonical + `Source:` rows, while generic URL validation accepted `mailto:` as a social + image. +- Root cause: broad URL checks prove syntax classes, not corpus provenance or + image semantics. +- Prevention: parse every Source row, bind the first and subsequent rows to + the exact locale/origin/version, reject query/fragment delimiters and + normalized duplicates, and forbid historical corpora. Validate `og:image` + and `twitter:image` separately as HTTPS or safe local image targets that + actually exist. + +## Apply one browser-safe URL shape policy to every request surface + +- Symptom: strict alias checks rejected external and protocol targets, but + `https:///docs/...` still passed ordinary link, `srcset`, object/media, and + CSS validation because Python parsed it as an HTTP URL with no authority and + a local-looking path. +- Root cause: URL trust checks were attached to individual consumers. Python + RFC parsing and browser WHATWG parsing disagree on malformed slash, + backslash, whitespace, and authority forms, so a path-only check can + authorize a browser request to another host. +- Prevention: validate URL shape before resolution and apply it to links, + actions, meta refresh, active resources, every `srcset` candidate, object and + media fields, inline styles, static CSS, action manifests, and artifact + metadata. HTTP(S) always requires an authority; protocol-relative, + backslash, whitespace/control, and ambiguous forms fail before origin or + target checks. Artifact validation must invoke the complete rendered + security scan, not assume a prior build-stage scan covers post-processing or + downloaded artifacts. diff --git a/.goal-task/oink-site-improvements/pr-a-body.md b/.goal-task/oink-site-improvements/pr-a-body.md new file mode 100644 index 000000000..5604c2e23 --- /dev/null +++ b/.goal-task/oink-site-improvements/pr-a-body.md @@ -0,0 +1,72 @@ +## Before → after + +| Before | After | +| --- | --- | +| Three release entries were split across configuration and build behavior. | `versions.json` drives one immutable `latest / 1.7 / 1.5 / 1.3 / 1.0` release contract, including selectors, aliases, SEO, and aggregate metadata. | +| Summary search had no durable load-failure recovery path. | Native summary search remains primary and exposes distinct empty/error states with a stable keyboard-accessible retry. | +| No optional AI integration contract existed. | Kapa is disabled by default, locale-bound, and loaded only after an explicit click; timeout, late response, and retry remain isolated from native search. | +| CI mixed build and publication concerns. | Fixed event plans build immutable artifacts, revalidate the aggregate, run Chromium gates, and publish only to reviewed ASF targets with minimal permissions. | + +## Main changes + +- Add the shared OINK shell behavior for navigation, version/locale-scoped + sidebar state, mobile isolation, focus restoration, theme, image zoom, + Backlinks, and Blog copy-link behavior. +- Keep local summary search authoritative while adding an optional Search Tail + + Floating Launcher Kapa adapter with privacy-safe click gating. +- Generate bilingual latest-only `llms-full.txt` files without adding them to + historical releases or making Kapa a build dependency. +- Build five immutable releases and preserve production historical links from + latest-only staging. A deterministic 195-page route map keeps users on the + equivalent logical page when it exists and gives a locale-correct, + one-time-explained Docs-root fallback when it does not. +- Replace the previous workflow with fixed production/staging plans, + short-lived artifacts, aggregate/security validation, Node 24, Playwright, + Chromium, and fixed ASF publication targets. +- Apply one fail-closed rendered-request policy to HTML, SVG, CSS, list-valued + image attributes, runtime URLs, and authored content boundaries. Bootstrap + control SVGs and shared historical assets remain local and version-complete. + +## Ask AI direction + +The selected design combines a contextual Search Tail with a restrained +Floating Launcher. It excludes a persistent side panel and the old red/pink +assistant treatment. + +<img width="860" alt="Ask AI interaction direction comparison" src="https://github.com/user-attachments/assets/013cceaa-fd72-47cf-88ff-69224e0ce32b"; /> + +Full decision record: https://github.com/apache/hugegraph-doc/issues/467#issuecomment-5541691334 + +## Validation + +- `bash dist/validate-links.sh` +- `python3 -m unittest discover -s scripts -p 'test_*.py' -v` — 124 passed +- `node --test tests/ui-ai/*.test.cjs` — 23 passed +- `node --test tests/e2e/workflow-contract.test.cjs` — 6 passed +- Five-version production aggregate — 1,082 HTML, 3,528 published files, + 10 error documents; all 195 logical route entries pass exact + forward/missing/reverse validation, including two explicit EN/CN renamed-page + equivalence groups +- Latest-only ASF OINK staging aggregate — 276 HTML, 845 published files, + 2 error documents; every historical selector remains on the production + origin +- Full ASF OINK staging aggregate — 1,082 HTML, 3,528 published files, + 10 error documents; current and historical routes remain on staging +- AI-enabled fixture — 276 HTML, 840 files +- EN/CN LLMSFULL — 87 canonical, unique, same-origin sources per locale; + historical LLMSFULL outputs remain absent +- Historical social metadata — 1,530 matching OG/Twitter entries with all four + version-scoped fallback images present; 59 static redirects are explicitly + distinguished from content pages +- Blocking Chromium suite — 32 passed, 3 expected PR-B-only skips +- Advisory visual matrix — 8/8 +- Authored-content boundary scan — ordinary, Print, and landing Print outputs + retain balanced markers; media nesting and duplicate attributes fail closed +- Final integrated re-review — exactly 3 independent reviewers, 3/3 CLEAR + +## Delivery boundaries + +- Kapa remains disabled until the reviewed EN/CN source groups, staging corpus, + CSP hosts, and live privacy/failure smoke checks pass. +- Community roster and content pilots remain isolated in PR-B. +- Full-content local search remains deferred and is tracked in #471. diff --git a/.goal-task/oink-site-improvements/pr-b-body.md b/.goal-task/oink-site-improvements/pr-b-body.md new file mode 100644 index 000000000..a089fe5ff --- /dev/null +++ b/.goal-task/oink-site-improvements/pr-b-body.md @@ -0,0 +1,42 @@ +## Before → after + +| Before | After | +| --- | --- | +| Community did not expose the ASF HugeGraph project roster. | One reviewed data bundle renders 12 PMC members and 10 Committers consistently in HTML, Print, and Markdown. | +| Member identity presentation could require browser-side lookups. | The page performs zero visitor-side roster requests; the confirmed empty GitHub mapping uses deterministic initials and ASF phonebook links. | +| Core documentation entry queries relied only on body text. | Restrained metadata for 12 bilingual entry groups places all 24 fixed queries in the Top 3 of the real OINK summary search. | +| Confirmed OINK content primitives were not exercised in product documentation. | Three latest-only bilingual page groups pilot steps, command/file controls, field anchors, wide tables, and request/response blocks. | + +## Main changes + +- Add a deterministic ASF roster refresh/validation pipeline using the public + committee, LDAP project, and LDAP people datasets. +- Preserve the last-good roster atomically: install and validate candidate + images first, replace the data bundle last, then clean orphaned assets. +- Render Project members after participation guidance with a 5/3/2 responsive + grid and same-origin 128×128 WebP assets. +- Keep GitHub mappings empty for this delivery. No identity is inferred from a + name, email address, organization membership, or commit history. +- Add bounded search metadata only to the 12 agreed EN/CN entry groups. +- Apply native OINK content components only to the three agreed bilingual + latest-page pilots. + +## Validation + +- Offline roster and rendering contracts: 35 passed +- Combined Python suite: 112 passed +- Actual OINK search ranking: 24/24 fixed queries in the Top 3 +- Community HTML/Print/Markdown parity: 12 PMC + 10 Committers +- Responsive grid: 5 columns at 1440px, 3 at 900px, 2 at 390/320px +- Integrated Node/Chromium gate: 49/49 +- Integrated five-version aggregate: 1,082 HTML, 3,414 files, + 10 error documents +- Advisory visual capture: 8/8 + +## Dependency + +This change is intentionally isolated from the shared shell, versioning, +workflow, and test workspace owned by #472. It will be rebased onto the merged +PR-A baseline before final merge. + +Closes #468 diff --git a/.goal-task/oink-site-improvements/state.md b/.goal-task/oink-site-improvements/state.md new file mode 100644 index 000000000..ace3b01bc --- /dev/null +++ b/.goal-task/oink-site-improvements/state.md @@ -0,0 +1,568 @@ +# OINK Site Improvements — Execution State + +## Status + +- Phase: cross-host handoff preparation after all local delivery code was + pushed. `handoff.md` is the portable destination-host entrypoint. +- PR-A is ready for review and its exact-head CI is fully green; required human + review remains pending. PR-B is pushed but its PR has not been created. +- Progress: 0/7 completion gates. +- Work-completion estimate: 65%; this is not a gate count and does not waive + any of the seven conjunctive completion gates. +- Resume entrypoint: refresh PR #472 exact head and required human review. CI + run `33934549197` is fully green as of the 2026-09-05 handoff refresh. If + branch protection permits, merge PR-A without override; then refresh + `master` and create PR-B from the already-pushed + `feat/oink-community-content` branch with `Closes #468`. + +Review-loop limit confirmed by the user: + +- Default to at most three review-fix rounds per milestone. +- Extend only a reproducible release-blocking Critical finding to a fourth or + fifth narrow re-review; never restart a broad review cycle. +- At the cap, record remaining non-high-severity findings in `todo.md` or the + final issue and continue independent work. An unresolved high-severity + finding keeps only its affected release gate open; it does not stop unrelated + lanes. + +## Confirmed outcome and scope + +Implement the complete plan in +`.goal-task/oink-site-improvements/design.md`: + +- PR-A: OINK core platform, five-version routing, Ask AI, CI/CD, and browser + acceptance. +- PR-B: ASF Project members, search metadata, and bilingual content-component + pilots. +- PR-C: the second-phase ASF-aware download experience after the first phase is + stable. +- Complete the specified Issue #467/#468 and full-text-search issue work, plus + the non-blocking OINK upstream proposals. + +The deferred list in the design is out of scope. Do not import the Docusaurus +implementation, translate missing historical content, mechanically rewrite +other pages, or make Kapa a dependency of native search or site publication. + +Unattended authority confirmed by the user: + +- Once required CI, branch protection, and any required human review all pass, + mark PR-A, PR-B, and PR-C ready and merge them without another prompt. +- Never use an administrator override or bypass a required review/check. +- Keep PR-B GitHub mappings empty and use the deterministic initials fallback; + do not infer or populate the 22 member identities. +- Continue the reviewed Kapa source-group/domain configuration without another + prompt. Only an expired session, CAPTCHA, or equivalent interactive account + challenge requires the user to return. + +## Current exact-head checkpoint + +Latest authoritative checkpoint at pause: + +- PR-A is clean and pushed at + `25f3e8c3f7982cbf1d08c4bda572e9da9add79eb`. PR #472 is no longer a draft; + it is `REVIEW_REQUIRED`. Exact-head CI run + `https://github.com/apache/hugegraph-doc/actions/runs/33934549197` completed + successfully across prepare, all five version builds, aggregate, E2E, + visual, and deploy; publish was correctly skipped for the PR event. Do not + merge until required human review and branch protection are green. +- PR-B is clean and pushed at + `bb270838626165ad2c98c11150dde39f4eb113c9` on + `origin/feat/oink-community-content`; no PR exists yet. +- Integration is clean at + `81092317458740eeaf9da8b289cb0ea7f226aaf2`. Its tree is byte-identical to + the synthetic union of the pushed PR-A and PR-B heads, so the local + integration branch contains no unique unpushed code. +- Remote `master` was rechecked immediately before both pushes and remained + `d88167dd797efafea50cec59909d57849703fde5`. +- The checkpoint applies one browser-safe contract to HTML, SVG, CSS, + `srcset`/`imagesrcset`, runtime `data-td-*` URLs, form/navigation attributes, + duplicate attributes, CSS escapes/functions, and local resource existence. + All rendered resource `data:` URLs are forbidden. Bootstrap's 20 embedded + control SVGs are now local files, and historical overlays copy those files + plus the two shared homepage hero images. +- PR-A exact-head matrix is fully green: links; Python 124/124; UI/AI 23/23; + workflow 6/6; production and staging-full five-version 1082-HTML aggregates; + 195-route byte equality; staging-latest 276 HTML; Chromium 32 passed with + three expected PR-B-only skips; visual 8/8. Evidence: + `/private/tmp/hgdoc-pra-25f-final.0CodtH/`. +- Integration exact-head matrix is fully green: links; Python 161/161; UI/AI + 23/23; workflow 6/6; production and staging-full five-version 1082-HTML + aggregates; route byte equality; staging-latest 276 HTML; Chromium 35/35 + with zero skips; visual 8/8; marker pairs 1009/1009 with zero unpaired; + Community landing HTML/Print EN/CN 4/4. Evidence: + `/private/tmp/hgdoc-integration-810-final.LiNnlr/`. +- The final integrated review stopped at the user-confirmed three-round cap. + The third round used exactly three independent reviewers and finished 3/3 + CLEAR with no unresolved material finding. +- Local preview servers at ports 4186 (PR-A) and 4187 (integration) were + stopped as part of the pause; both ports are no longer listening. +- PR-C baseline inventory is complete but implementation remains correctly + gated behind first-phase stability. EN/CN currently duplicate the same 31 + ASF artifacts and 93 mirror/ASC/SHA512 links per language. The planned + implementation uses one restricted ASF data source and a site adapter rather + than OINK's GitHub-release-only download resolver. + +Historical checkpoint detail below is retained as failure/recovery evidence; +any head or active status there is superseded by the latest checkpoint above. + +- PR-A local HEAD is + `73f31a44dd9c39e70fc2b8ce412ac56040d6b5b7`, twelve commits ahead of the draft + PR's remote head + `3adba9eeb7c0cbaa83d1568243954aab480f965a`. Remote `master` and the PR base + were re-fetched on 2026-09-05 and remain + `d88167dd797efafea50cec59909d57849703fde5`. +- The first exact-head PR-A matrix at `dc51b02e` passed links, Python 101/101, + UI/AI Node 23/23, workflow 6/6, and the first three production builds, then + correctly stopped when artifact validation exposed that the new social + validator rejected Hugo alias/redirect pages without social tags. Its + temporary evidence was removed after the failure was recorded here. +- Repair `127fbd733` identifies redirects before social validation, permits + only redirects with both social tags absent, and retains strict 1+1 matching + metadata on content pages and partial-tag failure. The final exact-head + PR-A matrix is fully green: links, Python 102/102, UI/AI Node 23/23, + workflow 6/6, production and staging-full five-version builds (1082 HTML), + staging-latest (276 HTML), 195-route byte equality, exact AI fixture, + Chromium 32 passed with three expected PR-B-only skips, and visual 8/8. Its + temporary evidence was removed after later validator commits superseded it. +- The integration worktree is clean at + `1d6e1303ff38bd1fc7e3b148e6da3628eb26a10c`, containing PR-A, PR-B, all + logical-equivalence/LLMS/social hardening, and the redirect-validator repair. + The superseded `aae94cdc6` matrix passed links, Python 136/136, UI/AI Node + 23/23, workflow 6/6, and all five production builds before reproducing the + same redirect false positive and stopping. That superseded temporary evidence + was removed after its failure was recorded. The final exact-head integration + matrix is now fully green: links, Python 137/137, UI/AI Node 23/23, + workflow 6/6, production and staging-full five-version builds (1082 HTML), + staging-latest (276 HTML), exact route equality, AI fixture, Chromium 35/35 + with zero skips, ranking 24/24, Community parity across all three artifact + modes, and visual 8/8. Evidence: + `/private/tmp/hgdoc-integration-97643.dYy6VS/` (removed after the new head + superseded it). Exactly three independent reviewers reviewed frozen clean + head `97643b328`: reviewer #1 was CLEAR; + reviewer #3 found that ordinary meta-refresh aliases can reuse a generic URL + validator that permits external/protocol URLs, while route generation can + discard an external authority and treat its path as local. The repair must + require same-origin, same-version-scope, existing artifact targets for + ordinary aliases while retaining only the exact `client-go` exception. + Reviewer #2 found that the security validator's fixed error-document list + covered only root/1.7/1.5 and omitted 1.3/1.0, even though the current ten + generated 404 pages are correct. The fix derives the complete set from the + version manifest and proves security-only publication checks reject SEO + regressions for every version. Those two fixes initially over-constrained + the intentional archived home redirects, which a new matrix and two + reviewers caught before push. Commit `8c99d6d` / integration `cca2d0b1e` + now permits only the exact archived English and Chinese home redirects while + retaining strict ordinary-alias validation. Focused tests and all four real + historical artifact validations pass. The next re-review found one remaining + WHATWG/parser ambiguity: `https:///...` has no authority under Python + `urlsplit` but browsers can interpret its first path segment as a host. + Commit `2b4e221` / integration `a7e349d` rejects authority-less HTTP(S) + aliases plus all whitespace/control characters and adds failing-first + fixtures. The following adversarial review proved aliases themselves closed + but found the same authority-less HTTP(S) ambiguity in ordinary rendered + links and the aggregate security-only validator. Commit `600b828` / + integration `8ad410135` centralizes the fail-closed URL-shape rule across + ordinary version validation and security-only/full aggregate scans, rejecting + authority-less HTTP(S), whitespace/control, backslashes, and protocol-relative + forms. The next adversarial review proved ordinary links closed but found + `srcset`, object/media resources, and CSS tokens were not all routed through + that policy. Commit `73f31a4` / integration `1d6e1303f` applies one shape + validator to every HTML/CSS request token and makes artifact validation call + the complete rendered security scan. Failing-first multi-resource fixtures, + Python 109/109, production/staging-full 1082-HTML scans, and staging-latest + 276-HTML validation pass. New exact-head matrices and all exactly three + adversarial reviews remain required. +- Draft [PR #472](https://github.com/apache/hugegraph-doc/pull/472) was + fast-forwarded without force to exact reviewed head `3adba9eeb`; remote + `master` remained `d88167dd7`. CI run + [33905024759](https://github.com/apache/hugegraph-doc/actions/runs/33905024759) + was cancelled while queued after the integrated review proved that head + incomplete; its cancelled jobs are not acceptance evidence. The PR remains + draft and `REVIEW_REQUIRED`; its body is prepared with the latest local + counts but must not be updated remotely until the new exact-head matrices and + three reviews clear. + +## Active truth and authority + +Use this order when sources conflict: + +1. latest user confirmation; +2. `.goal-task/oink-site-improvements/design.md`; +3. current source and tests at the refreshed Apache `master`; +4. Apache HugeGraph issues and PRs; +5. this state file and `todo.md`. + +Active paths: + +- `.goal-task/oink-site-improvements/design.md` — authoritative product, + interface, release, and acceptance design. +- `.goal-task/oink-site-improvements/state.md` — execution contract, gate + evidence, recovery entrypoint, and next action. +- `.goal-task/oink-site-improvements/todo.md` — item-level status, dependencies, + waits, and deferrals. +- `.goal-task/oink-site-improvements/lessons.md` — evidence-backed reusable + lessons promoted after concrete failures; not a progress log. +- `versions.json`, `hugo.yaml`, `.github/workflows/hugo.yml`, + `scripts/versioning.py`, `scripts/test_versioning.py`, and + `scripts/test_validate_site_output.py` — current implementation and validator + baseline. + +`AGENTS.md` still describes the pre-OINK Docsy/Hugo 0.102.3 site. Follow its +general bilingual and evidence requirements, but resolve obsolete technical +facts from the current source and CI. Updating it is not part of the confirmed +product scope. + +## Baseline + +- Initialized: 2026-09-04, Asia/Shanghai. +- Worktree: + `/Users/zhu/.codex/worktrees/10a2/hugegraph-doc`. +- Remote target: `https://github.com/apache/hugegraph-doc.git`. +- Baseline revision: `d88167dd797efafea50cec59909d57849703fde5`. +- `HEAD` and `origin/master` were equal and the worktree was clean at + the latest refresh. The primary worktree now uses + `feat/oink-core-platform` at that revision. +- GitHub account `imbajin` was authenticated with push access to + `apache/hugegraph-doc`. +- The refreshed baseline used OINK `v1.0.0`, Hugo `0.165.0`, and three + versions. PR-A now derives `latest / 1.7 / 1.5 / 1.3 / 1.0` from + `versions.json` and includes a Node 24/Playwright workspace. +- Issues #467 and #468 are open. No existing PR is assigned to PR-A, PR-B, or + PR-C. +- Full-content local search is now tracked separately in Apache + [Issue #471](https://github.com/apache/hugegraph-doc/issues/471); it records + the current summary baseline and labels the 233–243 KiB gzip figure as an + estimate rather than current-HEAD evidence. +- The Issue #467 Ask AI comparison board was generated with built-in + `image_gen` and saved as + `.goal-task/oink-site-improvements/evidence/ask-ai-visual-directions.png` + (1717×916, SHA-256 + `68a97ffa93941608fa6d112e77331e464df59a824b8073ebf1c5543a472c98c2`). + The recorded decision combines Search Tail and Floating Launcher, excludes a + persistent side panel and the old red/pink UI. It is published as + [Issue #467 V8 evidence](https://github.com/apache/hugegraph-doc/issues/467#issuecomment-5541691334); + final staging screenshots remain a later append-only checkpoint. +- Kapa website/integration ID + `0b277570-4740-451e-96fa-1e4ac1ac5e88` is confirmed in the authenticated + Apache HugeGraph admin project. The synchronized browser session is active. + Existing sources and the single `HugeGraph` product group were inspected + read-only; reviewed latest EN/CN source-group IDs do not yet exist. The + widget currently allows production and general staging, but not the + dedicated `https://hugegraph-oink.staged.apache.org` origin. Do not create + groups, sources, or the domain entry until the matching staging LLMSFULL + corpus exists. +- Baseline validation on the original initialization revision passed + `bash dist/validate-links.sh` and + `python3 -m unittest discover -s scripts -p 'test_*.py' -v` + (66 tests). +- Apache master then advanced through #470 from `b1ed7eb84` to + `d88167dd7`, synchronizing 1.7 content and changing 111 paths, including + `scripts/versioning.py`, its tests, both Docs roots, and planned content-pilot + pages. The primary and every implementation lane must use the new revision. +- A second direct `git fetch`, `git ls-remote origin refs/heads/master`, and + main-checkout comparison on 2026-09-04 confirmed + `origin/master = local master = d88167dd797efafea50cec59909d57849703fde5`. + PR-A, PR-B, UI, and versioning worktrees all reported this revision as an + ancestor before further integration. +- On `d88167dd7`, link validation and all 67 Python tests passed. + Baseline `hugo --minify` also passed with Hugo + `v0.165.0+extended`; it produced 520 EN/CN pages and 814 files in an isolated + temporary destination. +- The first versioning-lane baseline run exposed an existing path-safety defect: + `prepare_output_directory()` can treat a `/private/tmp` checkout root as a + disposable output after path canonicalization. The isolated worktree was + removed, its branch reference remained intact, and that lane must add a + regression guard for repository roots, ancestors, and checkout descendants + before continuing. +- The same defect later deleted the Community lane after its uncommitted roster + work had passed eight focused tests, offline validation, and a Hugo build. + The branch/worktree was rebuilt at `d88167dd7`; that lane is reconstructing + from retained tool evidence and must checkpoint small validated commits before + broader tests. Until the safety fix lands, no `/tmp` implementation worktree + may run the affected full versioning suite. +- Safety checkpoint `f1bffd0827d217ad17eecf5ba00ace793ecf3ff3` + was integrated into PR-A as `4753dedb7`; the focused deletion regression and + the complete 67-test Python suite both pass from the primary worktree. +- Despite that focused/current-checkout pass, the Community `/tmp` worktree was + deleted a third time while reviewer fixes were uncommitted. The versioning + lane and PR-B design review were interrupted; the Community branch was moved + to `/Users/zhu/.codex/worktrees/hgdoc-oink-community-review`. Cross-worktree + cleanup safety is an active high-priority investigation, and broad cleanup + tests remain paused outside the primary worktree. +- Read-only process and source audit found no command that intentionally + targeted the Community path and no surviving cleanup process. It confirmed a + remaining safety gap: `prepare_output_directory()` protects only its current + `ROOT`, not sibling or prunable Git worktrees. The active hypothesis is to + fail closed for every registered worktree plus any candidate below a `.git` + file/directory ancestor; a failing sibling-worktree regression must precede + the fix. +- Cross-worktree fix `5edda2d59` is now integrated. The old implementation + failed the new sibling-checkout regression before the fix; afterward four + focused safety tests, the complete 70-test Python suite, and a live + registered `/tmp` sibling check with `shutil.rmtree` mocked all rejected + deletion before it could occur. +- UI/AI checkpoints were integrated as `61e20f455` and `8d5bf876e`. + Integration found additional Sass compilation failures not covered by the + Node contracts. Commit `70fa04695` fixes the shared root cause; with an + isolated Hugo cache, the production build passes (520 pages, 817 files) and + all eight UI/AI Node tests pass. +- UI/AI hardening `4d6593dc6` is now integrated. The combined PR-A tree passes + 12/12 UI/AI Node contracts and all 67 Python tests. Default and AI-enabled + Hugo builds, enabled-artifact security validation, invalid-config failure, + sidebar/search browser interactions, click-before-zero-external-resource + checks, and the 1200×630 social image were independently exercised by the + lane; real Kapa opening and staging-derived CSP hosts remain external gates. +- Five-version core commit `9c14050d5` is integrated. The lane built and + validated latest, 1.7, 1.5, 1.3, and 1.0 from immutable refs with route, + canonical, manifest, alias, hreflang, and historical sitemap checks. The + workflow/E2E checkpoint and single-source handling for the static Hugo menu + remain under active integration. +- PR-A is now at `474874c` and includes the secure fixed-target workflow, + per-build immutable SHA fetch, 24-query browser ranking gate, shell/AI/ + Community/axe Chromium gates, eight advisory visual states, archive robots + fixes, and manifest-derived Hugo menus. The static version arrays were + removed from `hugo.yaml`. +- PR-A reviewer fixes are now checkpointed through `401134d`. Commit + `d3cf6cc` preserves production historical selectors in latest-only staging + and rejects existing parent symlinks before cleanup; `ffc41ad` stabilizes + search retry DOM, forces fresh Kapa retry requests, blocks late renders, + derives Kapa colors from the site token, and limits Backlinks to five before + expansion; `72989ad` propagates the historical origin through aggregate + revalidation and CI. The first reviewer re-review then found cross-operation + publication concurrency, a symlinked `RUNNER_TEMP` root, dark Kapa accent + drift, and a stale retry tooltip. Commits `79d12ba`, `1e7258f`, and + `67ff2e8` close those findings with targeted regressions. Current exact-HEAD + checks pass Python 77/77, UI/AI Node 15/15, and workflow contracts 5/5. A + direct latest-only browser fixture also + passes all 14 applicable latest/UI/AI/accessibility checks; the full + versioning browser lane passes against the current five-version aggregate: + 26 passed with 3 expected PR-B-only skips. The same aggregate contains 1082 + HTML files, 3413 published files, and 10 error documents; latest-only staging + aggregation contains 276 HTML and 822 published files with all historical + selectors remaining on the production origin. + The final three-reviewer cycle on `401134d` is clear for correctness, + design/accessibility, and security/privacy; no material finding remains. +- PR-A was pushed directly to Apache and opened as draft + [PR #472](https://github.com/apache/hugegraph-doc/pull/472). Its remote head + is exactly `fe551ba06a9afed24c864759acb8c257fb29c238` and base is `master`. + The first CI run built all five versions, then exposed a leading-dash + argparse seam in aggregate. Commit `fe551ba` binds the run-scoped suffix to + its option; workflow contracts are now 6/6 and the replacement exact-head CI + run is queued. No duplicate PR or branch existed before creation. +- PR-B implementation is checkpointed in six commits ending at + `d50bc28e85835e9325ff6b0e9ac789156a9e22bd`. Nine focused roster tests, + offline roster/render validation, minified Hugo build, 22-member parity + across six EN/CN HTML/Print/Markdown outputs, both LLMSFULL outputs, 276-HTML + security validation, link validation, and diff checks pass. Browser ranking, + the three-reviewer gate, and any human-reviewed GitHub mappings remain open. +- PR-B independent reviewer 1/3 reported four high-confidence Important + findings: unmapped ASF profile URLs were not enforced, equal public names + made ordering hash-dependent, orphan-cleanup failure could replace the + last-good roster, and product-output tests did not yet prove component/index/ + LLMSFULL behavior. The PR-B lane is fixing all four with targeted regression + evidence before reviewers 2/3 and re-review. +- Reviewer 1 re-review confirmed those first fixes, then found remaining gates + around real search ranking, CI wiring, strict Chair/avatar types and paths, + rollback-failure semantics, and fixed Hugo setup. Reviewer 2 found incorrect + Markdown ordering/title semantics, shared landing-dispatcher and LLMSFULL + ownership drift, and a stale ICC flag. Reviewer 3 added existing-avatar + verification, bounded/allowlisted network reads, actual WebP decoding, + identifier/Markdown escaping, and genuinely offline validation concerns. + PR-A now owns LLMSFULL plus ranking/CI setup; PR-B is addressing the remaining + data, section-specific rendering, and security findings before all three + reviewers re-review. +- PR-B is now at `b6e651c` after closing reviewer findings for pre-mutation path + validation, redirect allowlists, local and remote JSON schemas, real WebP + decoding, role-local real-link parsing/order, Markdown boundaries, and + cross-origin loading of its fingerprinted stylesheet. The fixed 24-query set + ranks 24/24 in the actual OINK search engine after the two targeted symmetric + boosts. +- PR-B final HEAD is `4d02fcb`. Exactly three independent reviewers re-reviewed + every fix and reported clear with no material finding. The integrated + ownership test also accepts PR-A's exact bilingual LLMSFULL contract while + continuing to reject LLMSFULL in standalone PR-B. +- Local integration branch `work/oink-integration` combines PR-A and PR-B. A + complete five-version production-origin run built and validated 3414 files, + 1082 HTML files, and 10 error documents. Blocking workflow contracts passed + 4/4 and Chromium passed 27/27; advisory visual capture passed 8/8. Screenshots + are retained under + `.goal-task/oink-site-improvements/evidence/browser/`. +- The refreshed integration head is `d91f5b55`. The first current-HEAD browser + run exposed that the search-retry fault injector used `route.continue()` and + bypassed the local aggregate remapper. Commit `58e7dba` switches the success + attempt to `route.fallback()`; the isolated regression passes and the + complete integrated Node/Chromium gate is now 49/49. The production + five-version aggregate remains green at 1082 HTML, 3414 files, and 10 error + documents; Python is 112/112 and advisory visuals are 8/8. +- OINK upstream proposals are filed as + [#40 search-tail/palette extension](https://github.com/pgsty/oink/issues/40) + and + [#41 sidebar disclosure/isolation contracts](https://github.com/pgsty/oink/issues/41). + The account has read-only code permission, so issues are the available + upstream delivery mechanism and upstream acceptance remains non-blocking. + +Refresh the remote revision, open PR/Issue state, staging/production deployment, +Kapa configuration, and write capability whenever those facts can affect an +action or claim. + +## Work structure and ownership + +- PR-A branch: create directly in `apache/hugegraph-doc` from the then-current + `master`. Use exclusive lanes for UI/AI, versioning/CI, and E2E. A single + integration owner owns shared configuration, lockfiles, workflows, generated + manifests, and the combined diff. +- PR-B branch: create directly in `apache/hugegraph-doc` from the then-current + `master`. It may run in parallel but must not edit PR-A-owned shared shell, + configuration, or workflow files. +- PR-C branch: create directly in `apache/hugegraph-doc` only after PR-A and + PR-B are integrated and the first-phase five-version build is stable. +- OINK upstream target: `github.com/pgsty/oink`. Upstream acceptance is not a + HugeGraph delivery gate; record the proposal/PR URL and retain the local + compatibility layer until a usable release exists. +- The authenticated GitHub account currently has read-only repository + permission on `pgsty/oink`; issue/proposal submission remains available, but + a direct upstream branch is not. OINK issue #24 already covered a distinct + cached-sidebar/JavaScript fallback bug and is closed, so new upstream reports + must avoid duplicating it. + +Every worker must record changed paths, exact commands, evidence, assumptions, +and unresolved risks. Workers must not overwrite another lane. The integration +owner resolves seams and reruns affected checks after combination. + +Current local branches/worktrees: + +- Integration: `feat/oink-core-platform` in the primary worktree. +- UI/AI lane: `work/oink-ui-ai` in `/tmp/hgdoc-oink-ui.Zix0W6`. +- Versioning/CI lane: `work/oink-versioning-ci`; its isolated worktree is being + reconstructed after the baseline path-safety failure described above. +- Community/content lane: `feat/oink-community-content` in + `/Users/zhu/.codex/worktrees/hgdoc-oink-community-review`. +- Integration validation: `work/oink-integration` in + `/Users/zhu/.codex/worktrees/hgdoc-oink-integration`. + +## Invariants + +- Native summary search remains complete and usable when AI is disabled, slow, + blocked, or broken. +- No Kapa active resource or request occurs before an explicit Ask AI action. + Only the trimmed query and locale-specific source group may leave the site. +- The five-version order and refs come from `versions.json`; all consumers are + derived from it. +- Historical content retains historical facts, missing Chinese pages are not + replaced with English, and only true bilingual equivalents receive + `hreflang`. +- Community roles derive from ASF public data; GitHub identity is never guessed. + Browser visitors make no GitHub or Whimsy roster requests. +- Publication code never executes untrusted candidate code in the write-enabled + job. `deploy` remains the required read-only gate. +- Staging and production native behavior remains usable if post-deploy Kapa + smoke fails. + +## Completion gates + +1. PR-A satisfies every behavior, versioning, AI, CI/CD, security, and artifact + contract in the design. +2. PR-B satisfies the deterministic roster, three-output parity, responsive + Community, search metadata, and bilingual component-pilot contracts. +3. PR-A and PR-B are merged or otherwise integrated on the reviewed target, and + one complete five-version integration build passes before publication. +4. Chrome or the available browser equivalent records functional and UI/UX + evidence for the required latest/history, EN/CN, desktop/mobile, light/dark, + keyboard, error, retry, and failure-isolation flows. Accessibility and + advisory visual results are reported separately. +5. Staging and production acceptance passes for native search, routes, legacy + aliases, language switching, Community privacy, and click-gated external + requests; initial Kapa corpus/source-group/CSP activation is verified before + enabling AI. Post-deploy Kapa smoke remains advisory as designed. +6. PR-C delivers the ASF-aware data-driven download page with mirror, official + source artifact, ASC, and SHA512 semantics, without presenting GitHub source + archives as ASF releases. +7. Issue #467, Issue #468 closure linkage, the new full-text-search issue, and + OINK upstream submissions are recorded; final integrated changes pass the + required independent review and re-review with no unresolved high-severity + finding. + +The existing confirmed repository checks include: + +```bash +bash dist/validate-links.sh +python3 -m unittest discover -s scripts -p 'test_*.py' -v +``` + +Record the exact added Node/Playwright commands only after their scripts and +lockfile exist. Do not replace browser interaction or publication acceptance +with a green build. + +## Execution loop + +Batch low-risk changes by shared module and validation surface. After each +frozen batch, run affected tests and targeted checks. Run complete builds, +browser matrices, aggregate checks, and integrated review at phase boundaries +and after the final diff freezes. Never weaken assertions, skip mandatory +checks, ignore exit codes, or report unobserved success. + +After each productive loop report: + +```text +Progress [██████░░░░] 60% (3/5 gates) +This loop: <completed work and evidence>; Remaining: <main open work>. +Next: <one primary action>. +``` + +Use the actual fixed denominator and never report 100% before all seven gates +pass. Before compaction, quota wait, handoff, or session end, update this file +with gate progress, latest commit, validation/review evidence, active waits, +uncommitted changes, and one next action. + +## Retry, waits, and recovery + +Try one failing item at most three times by default. Then record the exact +failure, evidence, attempted recovery, dependency, and unblock condition in +`todo.md`; mark it waiting, deferred, or needs input; move it and its dependents +behind independent work; continue the highest-value non-conflicting item; and +recheck at a phase boundary or when the condition changes. + +CI queues, downloads, Kapa/admin waits, staging propagation, quota limits, +first failures, and optional missing dependencies do not stop independent work. +Useful parallel work includes the next module inventory, non-conflicting +implementation, evidence maintenance, failure analysis, and acceptance +preparation. + +Set the overall goal `blocked` only when the same condition has recurred for at +least three goal turns and every meaningful remaining item, after recovery, +authorized alternatives, splitting, reprioritization, and completion of +independent work, still jointly depends on that same logical conflict, safety +boundary, or verified mandatory external dependency. + +## Authorization, safety, and remote effects + +All user-authorizable actions required inside this confirmed scope are already +approved, including local/environment changes, dependency installation, +browser uploads, entry of available credentials, worktrees, direct Apache +branches, commits, pushes, PR and Issue actions, tests, workflow dispatches, +review responses, and fixed staging/production publication. Do not ask again or +wait, defer, or mark work blocked because of an authorization prompt. + +This approval does not fabricate credentials, sessions, tools, source-group IDs, +or capabilities; override higher-priority safety boundaries; or authorize work +outside scope. Never expose or persist credential values in logs, screenshots, +state, commits, PRs, or issues. Record only redacted actions and outcomes. + +Before each destructive or remote mutation, record or verify its exact target +and impact. Direct source branches and PRs target `apache/hugegraph-doc`; +publication targets only `asf-staging-oink` or `asf-site` through the reviewed +workflow. Continue independent work when Kapa or another genuine capability is +unavailable while keeping its completion gate active. + +## Review and commits + +At every major behavior-change milestone, use exactly three independent +read-only reviewers on the integrated diff: correctness/tests, +design/boundaries, and security/maintainability. After fixes, re-review affected +changes. Run at most three fix/re-review rounds by default; unresolved failures +remain deferred and prevent completion. + +Create focused local milestone commits only after applicable validation and +review pass. Push the direct Apache branches only after rechecking their exact +head and target. A checkpoint commit may preserve a required baseline with +explicit unmet gates, but it does not imply review success or completion. diff --git a/.goal-task/oink-site-improvements/todo.md b/.goal-task/oink-site-improvements/todo.md new file mode 100644 index 000000000..47a22a91e --- /dev/null +++ b/.goal-task/oink-site-improvements/todo.md @@ -0,0 +1,168 @@ +# OINK Site Improvements — Work Items + +Item-level status, dependencies, waits, and deferrals live here. Update this +file after each productive loop; keep only counts and dependency summaries in +`state.md`. + +## Gate 1 — PR-A: OINK core platform + +- [x] Fix destructive output-path validation so canonical repository roots, + ancestors, and checkout descendants are rejected; focused regression passed + in checkpoint `f1bffd0827d217ad17eecf5ba00ace793ecf3ff3` and integration commit + `4753dedb7`. +- [x] Refresh `origin/master`, create the direct Apache PR-A branch/worktree, + and inventory current OINK extension seams, ownership boundaries, and tests. +- [x] Implement shared OINK theme tokens, five-group Documentation navigation, + single version selector, delayed pointer behavior, keyboard behavior, and + explicit sidebar collapse/restore. +- [x] Implement stable per-version/per-locale sidebar persistence, active-path + priority, stale-ID cleanup, localStorage fallback, mobile drawer isolation, + focus restoration, scroll unlock, and hamburger contrast. +- [x] Preserve summary search; add distinct no-results/load-failure states and + retry. +- [ ] Implement the click-loaded Kapa adapter and shared state machine with the + exact configuration, privacy, failure, timeout, late-response, focus, theme, + CSP, and disabled-mode contracts. Source/mock contracts are green; staging + source groups and exact observed CSP hosts remain. +- [x] EN/CN latest LLMSFULL outputs are implemented on PR-A and validated as + separate locale-specific files; real Kapa ingestion remains an external gate. +- [x] Add 1.3 and 1.0, finish making `versions.json` the sole source including + the static Hugo menu, implement immutable + ref resolution, route-map/aliases, logical-page switching, SEO/archive rules, + and genuine language fallbacks. Core build/validate is green. +- [x] Implement Backlinks, image zoom, Blog copy-link, reviewed social fallback + image, and the scoped non-content OINK capabilities assigned to PR-A. +- [x] Replace the Cartesian CI matrix with the confirmed event model, + permissions, artifact lifetimes, timeouts, aggregate/E2E/deploy gates, and + fixed publish targets. +- [x] Add the Node 24, lockfile, Playwright, and Chromium test workspace under + `tests/e2e/` without making Hugo production builds run npm. +- [x] Run targeted checks, full PR-A validation, browser acceptance, three + independent reviews, fixes, and re-review; then commit, push, and open PR-A. + Exact clean pushed head `25f3e8c` includes the rendered-request security and + authored-content boundary checkpoints. Its final matrix passes links, Python + 124/124, UI/AI 23/23, + workflow 6/6, production/staging-full five versions, staging-latest, + route-byte equality, Chromium 32 with three expected PR-B-only skips, and + visual 8/8. [PR #472](https://github.com/apache/hugegraph-doc/pull/472) is + ready for review at the exact head. +- [ ] Resume by checking CI run 33934549197 and required human review; merge + PR-A only when both are green, without override. + +## Gate 2 — PR-B: Community and content experience + +- [x] Refresh `origin/master`, create the direct Apache PR-B branch/worktree, + and confirm it does not modify PR-A-owned shared config, shell styles, + lockfiles, or workflow files. +- [x] Implement ASF roster refresh and offline validation with authoritative + owners/members/Chair/name rules, deterministic ordering, schema, staleness, + last-good atomic replacement, and orphan cleanup. +- [x] Populate any GitHub mappings only after login and numeric user ID receive + explicit human review; the current empty mapping intentionally avoids + inference and renders all 22 members through the required fallback. The user + explicitly confirmed this mapping must remain empty for this delivery. +- [x] Implement the bilingual Project members section, site-local partial, + same-origin 128×128 WebP assets, no-JS initials fallback, accessible profile + links, 5/3/2 responsive grid, and HTML/Print/Markdown parity. +- [x] Add restrained search metadata for the 12 fixed EN/CN latest entry + groups; the integrated real Lunr/Playwright gate ranks all 24 fixed queries + in the Top 3. +- [x] Apply OINK native content components only to the three confirmed latest + bilingual page groups. +- [x] Complete integrated browser matrices and exactly three independent + reviews with required fix/re-review. Final PR-B head `bb27083` is pushed to + `origin/feat/oink-community-content`; the exact integrated matrix and final + 3/3 review are green. +- [ ] After resume, create PR-B with `Closes #468`, then wait for CI/review and + merge without override. + +## Gate 3 — First-phase integration + +- [x] Combine PR-A and PR-B in a local integration worktree without changing + their independent PR ownership. +- [x] Resolve current seams and rerun source, build, aggregate, browser, + accessibility, privacy, route, CSP, and security checks. +- [x] Run one complete five-version integration build after both changes are + present. +- [x] Obtain three independent integrated-diff reviews and re-review all fixes. + Exact clean integration head `8109231` is the exact tree union of pushed + PR-A and PR-B. Its final matrix passes links, Python 161/161, UI/AI 23/23, + workflow 6/6, production/staging-full five versions, staging-latest, + route-byte equality, Chromium 35/35 with zero skips, visual 8/8, and all + marker/media/roster focused gates. The final third review round is 3/3 CLEAR. + +## Gate 4 — Browser and publication acceptance + +- [ ] Exercise every required latest/history, EN/CN, desktop/mobile, + light/dark, pointer/touch/keyboard, success/failure/retry flow in Chrome or + the available browser equivalent. The current automated matrix is 27/27 and + advisory visual capture is 8/8; delayed pointer/touch, real Kapa, and + post-deploy paths remain. +- [ ] Record each route/URL, action sequence, observed result, and before/after + screenshot; keep UI/UX, accessibility, build, artifact, CI, and PR evidence + distinct. +- [ ] Validate exact production-origin PR artifacts without publishing. +- [ ] Dispatch and validate `staging-next/latest` and `staging-next/full` using + trusted Apache branches and fixed confirmation mappings. +- [ ] Verify initial Kapa corpus, source groups, CSP, render, locale isolation, + privacy, timeout, and retry on staging before AI is enabled. +- [ ] Publish through the reviewed fixed-target workflow and verify production + and staging native-search failure isolation, routes, aliases, language + behavior, Community privacy, and click-gated external requests. +- [ ] Record post-deploy real Kapa smoke separately as advisory evidence. + +## Gate 5 — PR-C: ASF-aware download experience + +- [x] Inventory the current EN/CN download facts and OINK download resolver. + Both languages duplicate 31 ASF artifacts and 93 release links; OINK v1.0.0 + is GitHub-release-specific and has no ASC field, so PR-C needs a narrow ASF + data contract and site adapter. +- [ ] After first-phase stability, create the direct Apache PR-C branch from + refreshed `master`. +- [ ] Inventory duplicated EN/CN download facts and define the single + data-source contract without rewriting unrelated documentation. +- [ ] Implement the OINK download/checksum experience for ASF mirrors, official + source artifacts, ASC, and SHA512. +- [ ] Ensure GitHub-generated source archives are never labeled as ASF official + releases. +- [ ] Validate EN/CN parity, rendered links/artifacts, responsive browser + behavior, accessibility, three independent reviews, fixes, and re-review; + then commit, push, and open PR-C. + +## Gate 6 — GitHub issue and design evidence + +- [x] Add the prepared three-direction comparison + (`evidence/ask-ai-visual-directions.png`), the selected Search Tail + Floating + Launcher decision, and the prohibition on the old red/pink UI to + [Issue #467 V8](https://github.com/apache/hugegraph-doc/issues/467#issuecomment-5541691334). +- [ ] After staging validation, append final desktop/mobile, light/dark + screenshots and evidence to Issue #467 without overwriting history. +- [ ] Ensure PR-B closes Issue #468. +- [x] Open deferred full-text-search + [Issue #471](https://github.com/apache/hugegraph-doc/issues/471) with the + summary-search baseline, clearly labeled 233–243 KiB gzip planning estimate, + per-language/per-version performance boundary, and no implementation. + +## Gate 7 — OINK upstream and final closure + +- [x] Submit the generic search-tail extension API proposal to + `github.com/pgsty/oink`. +- [x] Submit the generic palette extension and sidebar-interaction fixes + upstream as OINK + [#40](https://github.com/pgsty/oink/issues/40) and + [#41](https://github.com/pgsty/oink/issues/41). +- [x] Record upstream URLs/status without making upstream acceptance block + HugeGraph delivery. +- [ ] Freeze the final integrated diff and evidence, rerun all applicable + completion gates, complete the final three-reviewer cycle and fix/re-review, + and confirm no unresolved high-severity finding. + +## Current waits and unresolved capabilities + +- Kapa EN source-group ID: create and record it after the reviewed staging + `/docs/llms-full.txt` corpus is reachable. +- Kapa CN source-group ID: create and record it after the reviewed staging + `/cn/docs/llms-full.txt` corpus is reachable. +- Kapa admin session/account: authenticated and inspected. The current source + groups and website integration are known; creation and activation remain + gated on the matching staging corpus and dedicated staging-domain entry.
