feat(assistant): add the in-page AI assistant to docs.celo.org (#2250)

AGENTS.md

@@ -11,6 +11,7 @@ Structural work in progress is tracked in the restructure epic, [#2266](https://
 - Content directories today: `home/`, `build-on-celo/`, `tooling/`, `contribute-to-celo/`, `operate/`.
 - `snippets/` holds reusable JSX/MDX (`/snippets/ColoredText.jsx`, `/snippets/YouTube.jsx`, `/snippets/AddNetworkButton.jsx`). Import with an absolute path after the frontmatter: `import {YouTube} from '/snippets/YouTube.jsx'`.
 - Static assets: `img/`, `images/`, `assets/`, `logo/`.
+- **Any `.js` file under the content root runs on every published page.** Mintlify injects them automatically — there is no allowlist and no way to scope one to a single page — and the same applies to `.css`. Treat a `.js` file here as production code shipped to every reader, not as content: it has full same-origin DOM access on pages that print contract addresses and RPC endpoints. Mintlify does not support a raw `<script src>` in MDX, so third-party scripts are injected programmatically from such a file (`assistant.js` is the example). Note `submodules/developer-tooling` sits under this root too.
 
 ### Commands
 
@@ -121,7 +122,7 @@ Numbers and addresses live on one canonical page; every other page links there i
 | Agent identity and trust | `/build-on-celo/build-with-ai/8004`, `/build-on-celo/build-with-ai/self-agent-id` | ERC-8004 registries on Celo; Self Agent ID adds a zero-knowledge proof-of-human |
 | Human identity | `/build-on-celo/build-with-self` | Self: passport / EU ID / Aadhaar proofs, nothing leaves the device |
 | Phone-number mapping | `/build-on-celo/build-on-socialconnect` | SocialConnect / ODIS |
-| AI tooling | `/build-on-celo/build-with-ai/use-docs-with-ai`, `/build-on-celo/build-with-ai/celopedia`, `/build-on-celo/build-with-ai/mcp/index` | docs MCP at `https://docs.celo.org/mcp`, `llms.txt`, per-page `.md`, Celopedia skill, Celo MCP server |
+| AI tooling | `/build-on-celo/build-with-ai/use-docs-with-ai`, `/build-on-celo/build-with-ai/celopedia`, `/build-on-celo/build-with-ai/mcp/index` | in-page Ask AI assistant, docs MCP at `https://docs.celo.org/mcp`, `llms.txt`, per-page `.md`, Celopedia skill, Celo MCP server |
 
 ### Partner contract addresses
 
@@ -136,7 +137,7 @@ Third-party (partner) contract addresses are not listed in these docs — link t
 
 ## 8. Writing for AI agents (discoverability)
 
-Most readers of these docs are now AI assistants and agents. Mintlify already serves them: `https://docs.celo.org/llms.txt` (index of every page's title and `description`), `llms-full.txt` (full text), every page as Markdown at its URL plus `.md`, the docs MCP server at `https://docs.celo.org/mcp`, and the page-level Copy / ChatGPT / Claude / Cursor menu. The [Celopedia skill](/build-on-celo/build-with-ai/celopedia) and the [Celo MCP server](/build-on-celo/build-with-ai/mcp/celo-mcp) are the other two entry points. Nothing needs configuring per page — but a page is only as useful to an agent as its text is explicit.
+Most readers of these docs are now AI assistants and agents. Mintlify already serves them: `https://docs.celo.org/llms.txt` (index of every page's title and `description`), `llms-full.txt` (full text), every page as Markdown at its URL plus `.md`, the docs MCP server at `https://docs.celo.org/mcp`, and the page-level Copy / ChatGPT / Claude / Cursor menu. Human readers also get the in-page [Ask AI assistant](/build-on-celo/build-with-ai/use-docs-with-ai), which answers from the same MCP endpoint. The [Celopedia skill](/build-on-celo/build-with-ai/celopedia) and the [Celo MCP server](/build-on-celo/build-with-ai/mcp/celo-mcp) are further entry points. Nothing needs configuring per page — but a page is only as useful to an agent as its text is explicit.
 
 Rules that make a page work for an agent:
 

assistant.js

@@ -0,0 +1,29 @@
+// Loads the docs AI assistant widget (celo-org/docs#2250).
+//
+// Mintlify includes every .js file in the content directory on all pages and
+// does not support a raw <script src> tag in MDX, so the widget is injected
+// programmatically. See AGENTS.md §1 for that mechanism.
+(function () {
+  var WIDGET_SRC = 'https://docs-assistant.celo.org/widget.js';
+
+  // The assistant API only accepts these origins. Injecting anywhere else
+  // renders a button that collects a question and then fails CORS, so limit
+  // the widget to hosts where it actually works — production plus local
+  // `mint dev`, which AGENTS.md asks contributors to run before a PR.
+  var HOSTS = ['docs.celo.org', 'localhost', '127.0.0.1'];
+  if (HOSTS.indexOf(location.hostname) === -1) return;
+
+  var script = document.createElement('script');
+  script.src = WIDGET_SRC;
+  // The widget reads this rather than inferring its own origin.
+  script.dataset.apiUrl = 'https://docs-assistant.celo.org/api/chat';
+  script.referrerPolicy = 'strict-origin';
+  script.onerror = function () {
+    // An ad blocker, an outage, or a blocked request otherwise leaves no
+    // button and no explanation for a reader told one would be there.
+    console.warn(
+      '[celo-docs] The AI assistant failed to load. It may be blocked by an extension or temporarily unavailable.'
+    );
+  };
+  document.head.appendChild(script);
+})();

build-on-celo/build-with-ai/use-docs-with-ai.mdx

@@ -1,15 +1,16 @@
 ---
 title: "Use Celo Docs with AI Tools"
 sidebarTitle: "Docs for AI Tools"
-description: "Connect docs.celo.org to Claude Code, Cursor, VS Code, and ChatGPT using the docs MCP server, llms.txt, and per-page Markdown."
+description: "Ask questions in-page with the docs assistant, or connect docs.celo.org to Claude Code, Cursor, VS Code, and ChatGPT using the docs MCP server, llms.txt, and per-page Markdown."
 ---
 
 **Point your AI assistant at the docs instead of its training data.** Everything on docs.celo.org is available in machine-readable form — a hosted MCP server your editor can query live, a full-text index for pasting into a chat, and a Markdown version of every page.
 
 This matters because model training data goes stale. Celo became an Ethereum L2 in March 2025, contract addresses change, and assistants confidently repeat outdated L1 details. Connecting your tool to these endpoints means answers come from the current docs.
 
-| Entry point | URL | Best for |
-|-------------|-----|----------|
+| Entry point | Where | Best for |
+|-------------|-------|----------|
+| In-page assistant | **Ask AI** button on any page | Quick questions while reading, without leaving the docs |
 | MCP server | `https://docs.celo.org/mcp` | Editors and agents — live search, no copy-paste |
 | Docs index | [`/llms.txt`](https://docs.celo.org/llms.txt) | Giving a chat a map of every docs page |
 | Full corpus | [`/llms-full.txt`](https://docs.celo.org/llms-full.txt) | Long-context models that can hold the whole docs set |
@@ -196,6 +197,22 @@ Reach for `llms.txt` by default. It costs a fraction of the tokens, and any tool
 
 Both files are generated from the live site, so they never go stale.
 
+## Ask a question in the docs
+
+Every page has an **Ask AI** button in the bottom-right corner. It answers from the documentation and links the pages it used, so you can check the source rather than take the answer on trust.
+
+It searches the same content as the MCP server above, which means answers reflect the docs as currently published — not a model's training data.
+
+If an answer arrives without any links, the assistant offers a **Try a more thorough answer** button, which re-runs the question against a stronger model.
+
+<Warning>
+  Answers are AI-generated and can be wrong. Follow the citations before relying on anything load-bearing, especially contract addresses and code. An answer with no links is not grounded in these docs — treat it as a starting point, not a source.
+</Warning>
+
+<Note>
+  **Where your question goes.** Questions are sent to Anthropic to generate the answer, and are logged along with the pages cited so we can find documentation gaps — questions that return no citation are reviewed weekly. Don't include secrets, private keys, or personal data.
+</Note>
+
 ## Copy any page as Markdown
 
 Every page has a contextual menu beside its title: