[Feature] Enable Ask AI with Kapa: Source Groups, ASF CSP, and Privacy Compliance

[imbajin]

Goal

Track the remaining follow-up tasks to enable Ask AI (Kapa.ai integration) for Apache HugeGraph documentation website following the OINK site integration in #493 and #472.

This issue serves as a sub-issue of #469 to coordinate source-group configuration, ASF Infra Content Security Policy (CSP) compliance, and privacy boundary verification before turning on the feature flag in production.

---

Background & Current State

• The frontend integration, UI layout, search-tail trigger, and same-origin consent dialog have already been implemented and merged in feat: complete OINK site integration #493.
• To ensure full compliance with Apache Software Foundation (ASF) privacy policy and prevent unconsented third-party requests, the feature is currently disabled by default in hugo.yaml:

  ai_search:
    enabled: false
    kapa:
      website_id: "00000000-0000-0000-0000-000000000000"
      source_group_id: ""

• Native documentation search operates independently without third-party dependencies.

---

Action Items / TODOs

1. Kapa AI Source Group Configuration

• Create and configure independent Kapa.ai Source Groups for English (EN) and Chinese (CN) documentation spaces.
• Update hugo.yaml with the official Source Group IDs (ai_search.kapa.source_group_id / source_group_id_cn).
• Verify locale isolation (e.g., Chinese queries retrieve Chinese docs; English queries retrieve English docs).
• Validate answer accuracy, citations, and markdown rendering quality.

2. ASF Infra CSP & Privacy Compliance

• Confirm exact Kapa widget and bot-protection domains with ASF Infra and VP Data Privacy:
  • kapa.ai, *.kapa.ai
  • hcaptcha.com, *.hcaptcha.com
• Add approved domains to the ASF Infra CSP whitelist (CSP_PROJECT_DOMAINS or .htaccess CSP directives).
• Ensure privacy boundaries are strictly upheld:
  • data-consent-required mode enabled.
  • Zero third-party network requests or cookies before explicit user consent in the dialog.
  • Disabled analytics cookies and fingerprinting.
  • Native search fallback if Kapa fails, times out, or user declines consent.

3. Staging Smoke Test & Production Rollout

• Conduct end-to-end browser smoke test on staging environment (hugegraph-oink.staged.apache.org or hugegraph.staged.apache.org).
• Verify timeout, cancellation (Escape / Cancel), retry behavior, and mobile responsiveness.
• Submit a single-line PR flipping ai_search.enabled: true in hugo.yaml once staging proof and ASF approval are confirmed.

---

Related Apache Precedents & References

The following Apache projects provide valuable reference for Kapa integration, privacy compliance, and CSP configuration:

• Apache Fluss PR #3760: Uses Kapa's data-consent-required, disables analytics cookies, and adds Kapa/reCAPTCHA domains to ASF .htaccess CSP.
• Apache ShenYu PR #1131: Documents locale/dark-mode integration, disabled analytics cookies/fingerprinting, and CSP entries for widget, proxy, and bot-protection domains.
• Apache Iceberg Issue #13934: Tracks Kapa's Open Source Program as a project-level adoption discussion.
• Apache SkyWalking Issue #12407: Records the removal of Kapa per ASF Policy team request, highlighting that production approval must be explicitly verified and cannot be assumed solely from staging availability.
• Apache Fluss Issue #3206: Reminder that deployed widgets require real browser smoke tests across desktop and mobile.

---

Follow-up Questions for ASF Infra / Privacy

1. Is the Kapa/hCaptcha integration allowed for testing on hugegraph-oink.staged.apache.org prior to formal ASF policy approval?
2. If staging is allowed, which exact production domains and CSP directives must be submitted to ASF Infra before enabling on hugegraph.apache.org?
3. Does Kapa require separate project-level approvals for dual English and Chinese source groups?

---

Coordination

• Parent Issue: [Website] Track post-OINK improvements #469 ([Website] Track post-OINK improvements)
• Related PR: feat: complete OINK site integration #493 (feat: complete OINK site integration)
• Related PR: feat: harden OINK platform and version delivery #472 ([Feature] Introduce OINK modern theme with Hugo multi-version support)
• Deferred search issue: Track full-content local search with a performance budget #471