[open-inspect-hydra]

Summary

Keeps the website FAQ's HydraDB database up to date, so the FAQ box on hydradb.com (POST /faq/ask, hydradb-application #2368) answers from current docs and site pages. Tracked as PRO-2899, a follow-up to PRO-2776.

What it syncs (one knowledge_base app source per page)

• Docs: the v2 "Guides" tab pages listed in docs.json.
  • The body comes from the repo's MDX: fenced code is kept verbatim, and component attribute text is kept (Field name/type, Tab/Step/Accordion/Card titles).
  • url = https://docs.hydradb.com/<page path>.
• Website: hydradb.com/, /ai, /contact, /alternatives, every /alternatives/* page (from sitemap.xml), and /privacy-policy.
  • Readable text comes from an HTML parser that prefers <main>, then <article>, then the page.
  • /blog/* and /terms-of-service are never ingested.
• faq/qa.yaml: a hand-written Q&A list. It ships empty. Ids come from the question text, not its position.

How it runs

1. Build the full set. Any input that can't be read stops the run with a non-zero exit, before anything is ingested or deleted: a page, the sitemap, docs.json, faq/qa.yaml, PyYAML, a bad or duplicate Q&A entry, or an empty body. A failed read is never treated as a removed page.
2. Ingest with POST /context/ingest (upsert=true) into the database's default collection, the one /faq/ask searches. Any per-item error fails the run.
3. Wait until every item is completed (GET /context/status). Any errored item, or 20 minutes without finishing, fails the run, so the old content stays.
4. Delete sources no longer in the set (POST /context/list, DELETE /context). Only ids this sync owns (docs-, site-, qa-) are ever deleted.

When it runs (.github/workflows/sync-faq.yml)

• On a push to main that touches the Guides pages, docs.json, faq/ or the sync itself
• Weekly, Monday 06:00 UTC, for website changes
• Manually, with workflow_dispatch

One run at a time (concurrency group), with a 30-minute timeout.

Config (already set on this repo)

• Secret HYDRADB_FAQ_API_KEY: a Read & write key for the FAQ database. Without it, the run skips with a notice and exits 0.
• Variable HYDRADB_FAQ_DATABASE = website-faqs. Required, with no default; it must match FAQ_DATABASE in hydradb-application.

Testing

• scripts/test_sync_faq.py (unittest, run in CI by the new faq-sync-tests job) covers:

  • void elements, nested wrappers and <main> preference
  • component attribute text and imports inside code
  • Q&A ids and a missing Q&A file
  • waiting for indexing and failing on an errored item

  Seven of the nine fail on the previous version of the script.

• Dry run: HYDRADB_FAQ_DATABASE=website-faqs python scripts/sync_faq.py --dry-run gives 42 items (24 docs, 18 site).

• Full run against a local HydraDB stack:

  • 42 items ingested. Items that hit the local stack's invalid provider key ended errored, and the run stopped with exit 1 and deleted nothing.
  • Separately, list_existing_ids + delete_ids against the same stack removed a planted stale site- source and left an unrelated source alone.

Files

• scripts/sync_faq.py: the sync (stdlib, plus PyYAML for faq/qa.yaml)
• scripts/test_sync_faq.py: tests
• faq/qa.yaml: the Q&A list, empty
• .github/workflows/sync-faq.yml: the sync workflow
• .github/workflows/ci.yml: adds the faq-sync-tests job

Closes PRO-2899. Pairs with hydradb-application #2368.

Open-Inspect session: https://open-inspect.hydradb.com/session/92fe275c740e14574aa75f4dc78331d0

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cortex-ai	🟢 Ready	View Preview	Oct 19, 2026, 8:22 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

✅ Mintlify Hygiene

No issues found.

[openhack-agent]

✅ OpenHack Summary

Security review of [PRO-2899] feat(faq): sync website-faq knowledge base from docs, site, and Q&A. 5 changed files; 0 findings at or above the low reporting threshold.

0   0   0   0

Confidence Score: 5/5

No reportable security findings were detected in this scan.

Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage.

Files Needing Attention: None

Important Files Changed

• .github/workflows/ci.yml (modified)
• .github/workflows/sync-faq.yml (added)
• faq/qa.yaml (added)
• scripts/sync_faq.py (added)
• scripts/test_sync_faq.py (added)

Last reviewed commit: 8c316d2 · View review on OpenHack

---

TIP: Mention @openhack-agent in a PR comment to request a review or ask a question. Use @openhack-agent fix all for every finding, or @openhack-agent fix unresolved threads for open review threads only.

[openhack-agent]

OpenHack reviewed this commit. See the OpenHack Summary for the confidence score and fix actions.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The sync affects the bounded knowledge database used by the public website FAQ.

The database-setting issue still needs to be fixed before merging.

Findings

1.  Sync targets the wrong database ▶

Summary

Adds a scheduled FAQ sync for Guides, selected website pages, and reviewed Q&A.

• The FAQ source set includes current guide pages, selected website pages, and reviewed answers.
• The FAQ database refreshes on relevant changes, on a weekly schedule, or on demand.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Push, weekly schedule, or manual run] --> B{API key present?}
    B -- No --> C[Skip with notice]
    B -- Yes --> D[Check database setting]
    D --> E[Read Guides, website pages, and Q&A]
    E --> F[Upsert items]
    F --> G[Wait for indexing]
    G --> H[Delete stale owned sources]
    E -- Read failure --> I[Fail without writing]
    G -- Error or timeout --> J[Fail without cleanup]

Loading

_{Reviews (3) · Last reviewed commit: "fix(faq): address review findings on the..." · Reviewed by Greptile}