story: Research and add an AI assistant to docs.celo.org (Mintlify-compatible, open source preferred)
- Dominant language
- MDX
- Stars
- 90
- Forks
- 382
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 35
Description
Part of #2266.
### User story
As a developer or AI agent reading the docs, I want to ask questions in-page and get cited answers, so I don't have to leave the site to find out how something works on Celo.
### Context & evidence
The in-site assistant disappeared with the Mintlify plan change. Mintlify's own assistant requires the Pro plan and above — **not an option; we are not going back to Pro.**
What already ships (verified live at `bdf40b37`):
- `https://docs.celo.org/llms.txt` → 200 (39 KB)
- `https://docs.celo.org/llms-full.txt` → 200 (1.5 MB)
- per-page `.md` export (e.g. `/build-on-celo/build-with-ai/overview.md`) → 200
- `https://docs.celo.org/mcp` → 405 on GET (the hosted MCP endpoint exists; it expects POST)
- `docs.json` `contextual.options`: copy, view, mcp, chatgpt, claude, cursor, vscode
So the content is already machine-readable. What's missing is the in-page chat.
### Part 1 — research (post the result as a comment, then decide)
Compare options that can be embedded in a Mintlify site (custom JS / `docs.json` scripts, or a hosted widget) on:
| Criterion | Why |
|---|---|
| Open source / self-hostable? | Preferred; avoids another vendor lock-in |
| Monthly cost | Must be recorded before the decision |
| Ingestion source | Can it index `llms-full.txt`, per-page `.md`, or talk to the `/mcp` endpoint directly, so there is no second content pipeline? |
| Answer citations | Links back to the docs page |
| Question analytics | Unanswered questions are a docs-gap signal |
| Data / privacy terms | What leaves our control |
| Maintenance burden | Who keeps it running |
Candidates to evaluate (OPEN — not an endorsement, extend the list): open-source self-hosted docs-chat projects; hosted docs-chat vendors with free or OSS tiers; a thin widget over the existing `/mcp` endpoint; Celopedia as the assistant backend.
Deliverable: a comparison table + recommendation + cost.
### Part 2 — implement the chosen option
### Acceptance criteria
- [ ] Comparison table posted with a recommendation and monthly cost
- [ ] Decision recorded in this issue
- [ ] Assistant live on every page of docs.celo.org
- [ ] Answers cite docs pages
- [ ] `build-on-celo/build-with-ai/use-docs-with-ai.mdx` updated to mention it
- [ ] Ops: any API key stored as a repo/org secret; owner named
### Non-goals
Analytics (#2249); the "AI resources" page (#2261); re-subscribing to Mintlify Pro.
### Depends on / blocks
No dependencies. OPEN: the implementer may change once the option is picked.
**Measured at:** `bdf40b37`
Contributor guide
Assessment
This issue has not been assessed yet.