From d5de544a617ea8e17270d918165c113094791a01 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Tue, 25 Aug 2026 15:29:30 +0100
Subject: [PATCH 1/5] test: verify custom JS injection for the docs assistant
 (#2250)

Trivial marker script to confirm Mintlify's content-directory JS
injection works on the current plan before building the real widget
loader.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 assistant.js | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 assistant.js

diff --git a/assistant.js b/assistant.js
new file mode 100644
index 000000000..bb40e94bf
--- /dev/null
+++ b/assistant.js
@@ -0,0 +1,5 @@
+// Injection test for the docs AI assistant (celo-org/docs#2250).
+// Mintlify loads every .js file in the content directory on all pages;
+// this marker verifies that works on the current plan before the real
+// widget loader replaces it.
+console.log('[celo-docs-assistant] custom JS injection OK');

From 57e8c83a0c9eb40262ecbce154f8eefa3d9d7716 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Wed, 26 Aug 2026 09:19:46 +0100
Subject: [PATCH 2/5] feat(assistant): load the docs AI assistant widget on
 every page

Replaces the injection-test marker with the real loader. The widget is
served from the assistant deployment and answers from the docs MCP
endpoint with links back to the pages it used.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 assistant.js | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/assistant.js b/assistant.js
index bb40e94bf..0e3222478 100644
--- a/assistant.js
+++ b/assistant.js
@@ -1,5 +1,14 @@
-// Injection test for the docs AI assistant (celo-org/docs#2250).
-// Mintlify loads every .js file in the content directory on all pages;
-// this marker verifies that works on the current plan before the real
-// widget loader replaces it.
-console.log('[celo-docs-assistant] custom JS injection OK');
+// Loads the docs AI assistant widget on every page (celo-org/docs#2250).
+//
+// Mintlify includes every .js file in the content directory on all pages, but
+// does not support a raw <script src> tag in MDX, so the widget is injected
+// programmatically. The widget itself and the API it calls are served from the
+// assistant deployment; it derives its own API origin from this src.
+(function () {
+  var WIDGET_SRC = 'https://docs-ai-assistant-ten.vercel.app/widget.js';
+
+  var script = document.createElement('script');
+  script.src = WIDGET_SRC;
+  script.async = true;
+  document.head.appendChild(script);
+})();

From 13f733f888fa232105d3f7576b0cf065e95786f5 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Wed, 26 Aug 2026 09:20:10 +0100
Subject: [PATCH 3/5] docs(ai): document the in-page docs assistant

Adds the Ask AI button to the entry-point table and a short section
covering what it answers from, that it cites its sources, and that
uncited gaps feed back into what gets written.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 build-on-celo/build-with-ai/use-docs-with-ai.mdx | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/build-on-celo/build-with-ai/use-docs-with-ai.mdx b/build-on-celo/build-with-ai/use-docs-with-ai.mdx
index c78d19508..3caf64a26 100644
--- a/build-on-celo/build-with-ai/use-docs-with-ai.mdx
+++ b/build-on-celo/build-with-ai/use-docs-with-ai.mdx
@@ -10,6 +10,7 @@ This matters because model training data goes stale. Celo became an Ethereum L2
 
 | Entry point | URL | 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,16 @@ 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.
+
+<Note>
+  Answers are AI-generated. Follow the citations before relying on anything load-bearing, especially contract addresses and code. If the docs don't cover your question, the assistant says so instead of guessing — and that gap is a signal we use to decide what to write next.
+</Note>
+
 ## Copy any page as Markdown
 
 Every page has a contextual menu beside its title:

From 196ed686d16e7ae677f02e4f493a2dd6b30b49a8 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Thu, 27 Aug 2026 20:23:05 +0100
Subject: [PATCH 4/5] feat(assistant): point the widget at the branded
 docs-assistant.celo.org host

Swap the temporary Vercel preview URL for the production CNAME now that it
resolves (200, application/javascript).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 assistant.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/assistant.js b/assistant.js
index 0e3222478..5e4c69171 100644
--- a/assistant.js
+++ b/assistant.js
@@ -5,7 +5,7 @@
 // programmatically. The widget itself and the API it calls are served from the
 // assistant deployment; it derives its own API origin from this src.
 (function () {
-  var WIDGET_SRC = 'https://docs-ai-assistant-ten.vercel.app/widget.js';
+  var WIDGET_SRC = 'https://docs-assistant.celo.org/widget.js';
 
   var script = document.createElement('script');
   script.src = WIDGET_SRC;

From 678361053de1919291cda422f3dbb0009b3efd74 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Mon, 31 Aug 2026 21:29:01 +0100
Subject: [PATCH 5/5] =?UTF-8?q?fix(assistant):=20address=20review=20?=
 =?UTF-8?q?=E2=80=94=20scope=20the=20loader,=20correct=20the=20docs=20clai?=
 =?UTF-8?q?ms?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Blockers:
- The loader injected on every host while the API only accepts
  docs.celo.org, so on `mint dev` and previews the button appeared,
  took a question, then failed CORS. It now runs only on hosts the API
  accepts, and localhost is being added to the allowlist so the feature
  can actually be reviewed.
- The page promised the assistant "says so instead of guessing" for
  uncovered questions, directly after the caution to follow citations.
  Uncited answers are a case the UI handles with an escalation button,
  not a refusal, so the guarantee withdrew the page's only safety
  warning. Describes the button instead and keeps the caution.
- Says where unanswered questions land rather than implying a feedback
  loop that is not visible here.

Also: an onerror on the injection, since an ad blocker or outage
otherwise leaves no button and no explanation; an explicit
data-api-url; strict-origin referrer policy; and the no-op async
dropped.

Docs and AGENTS.md: the assistant added to the frontmatter description
so it reaches llms.txt, the table's URL column renamed to Where since
its first row holds a button label and the table ships in
llms-full.txt, the AI tooling row and the fixed entry-point count
updated, and §1 now records that any .js under the content root runs
on every published page.

mint broken-links: success, no broken links found.

Refs #2250

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 AGENTS.md                                     |  5 ++--
 assistant.js                                  | 25 +++++++++++++++----
 .../build-with-ai/use-docs-with-ai.mdx        | 14 ++++++++---
 3 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 365ea9c6c..a56badb36 100644
--- a/AGENTS.md
+++ b/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:
 
diff --git a/assistant.js b/assistant.js
index 5e4c69171..009e49056 100644
--- a/assistant.js
+++ b/assistant.js
@@ -1,14 +1,29 @@
-// Loads the docs AI assistant widget on every page (celo-org/docs#2250).
+// Loads the docs AI assistant widget (celo-org/docs#2250).
 //
-// Mintlify includes every .js file in the content directory on all pages, but
+// 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. The widget itself and the API it calls are served from the
-// assistant deployment; it derives its own API origin from this src.
+// 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;
-  script.async = true;
+  // 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);
 })();
diff --git a/build-on-celo/build-with-ai/use-docs-with-ai.mdx b/build-on-celo/build-with-ai/use-docs-with-ai.mdx
index 3caf64a26..e64b26170 100644
--- a/build-on-celo/build-with-ai/use-docs-with-ai.mdx
+++ b/build-on-celo/build-with-ai/use-docs-with-ai.mdx
@@ -1,15 +1,15 @@
 ---
 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 |
@@ -203,8 +203,14 @@ Every page has an **Ask AI** button in the bottom-right corner. It answers from
 
 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>
-  Answers are AI-generated. Follow the citations before relying on anything load-bearing, especially contract addresses and code. If the docs don't cover your question, the assistant says so instead of guessing — and that gap is a signal we use to decide what to write next.
+  **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