Improve AI docs discoverability + canonicalize AI artifact origin

README.md

@@ -108,6 +108,8 @@ The build also generates AI-friendly artifacts that will be served by the hosted
 - `build/ai/docs.jsonl` (served as `/ai/docs.jsonl`)
 - `build/ai/raw/` (served as `/ai/raw/`)
 
+Artifact URLs default to `https://docs.yearn.fi`. To generate artifacts against a preview deployment, set `DOCS_URL` explicitly (for example `DOCS_URL=https://<preview-host>`).
+
 ## Configure .env
 
 The docs site pulls data from on-chain smart contracts, so an API key is necessary. The default is an Alchemy API key so the easiest thing to do is get a free api key from them at https://www.alchemy.com/pricing.

docs/getting-started/llm-friendly-docs.md

@@ -0,0 +1,51 @@
+# LLM Friendly Documentation
+
+This page makes it easy to share Yearn docs with an LLM using machine-readable endpoints built from the docs site.
+
+## Canonical endpoints
+
+- https://docs.yearn.fi/llms.txt
+- https://docs.yearn.fi/ai/manifest.json
+- https://docs.yearn.fi/ai/docs.jsonl
+- https://docs.yearn.fi/ai/raw/
+
+## Example prompt
+
+```text
+Use https://docs.yearn.fi/llms.txt as the entry point. Read the linked AI endpoints to answer my question, and cite canonical Yearn docs URLs from https://docs.yearn.fi in your response.
+```
+
+## Install the Yearn Docs Skill
+
+You can also install the Yearn docs skill, which is published from this docs site and gives instructions to query the docs:
+
+- https://docs.yearn.fi/skills/yearn-docs-site-query/SKILL.md
+- https://docs.yearn.fi/skills/yearn-docs-site-query/scripts/yearn_docs_query.py
+
+### Codex
+
+Give this to Codex as the steps to install:
+
+```bash
+SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/yearn-docs-site-query"
+mkdir -p "$SKILL_DIR/scripts"
+curl -fsSL https://docs.yearn.fi/skills/yearn-docs-site-query/SKILL.md -o "$SKILL_DIR/SKILL.md"
+curl -fsSL https://docs.yearn.fi/skills/yearn-docs-site-query/scripts/yearn_docs_query.py -o "$SKILL_DIR/scripts/yearn_docs_query.py"
+chmod +x "$SKILL_DIR/scripts/yearn_docs_query.py"
+```
+
+Restart Codex after installation so the new skill is loaded.
+
+### Claude Code
+
+Give this to Claude as the steps to install:
+
+```bash
+SKILL_DIR="$HOME/.claude/skills/yearn-docs-site-query"
+mkdir -p "$SKILL_DIR/scripts"
+curl -fsSL https://docs.yearn.fi/skills/yearn-docs-site-query/SKILL.md -o "$SKILL_DIR/SKILL.md"
+curl -fsSL https://docs.yearn.fi/skills/yearn-docs-site-query/scripts/yearn_docs_query.py -o "$SKILL_DIR/scripts/yearn_docs_query.py"
+chmod +x "$SKILL_DIR/scripts/yearn_docs_query.py"
+```
+
+In Claude Code, run `/help` and look for `/yearn-docs-site-query`.

scripts/generateAiArtifacts.ts

@@ -100,14 +100,6 @@ function resolveSiteOrigin() {
   const explicit = process.env.DOCS_URL?.trim()
   if (explicit) return explicit.replace(/\/+$/, '')
 
-  const vercel = process.env.VERCEL_URL?.trim()
-  if (vercel) {
-    const withProto = vercel.startsWith('http://') || vercel.startsWith('https://')
-      ? vercel
-      : `https://${vercel}`
-    return withProto.replace(/\/+$/, '')
-  }
-
   return 'https://docs.yearn.fi'
 }
 

sidebars/sidebarsContributing.js

@@ -92,5 +92,10 @@ module.exports = {
         'documentation/writing-style-guide',
       ],
     },
+    {
+      type: 'link',
+      label: 'LLM Friendly Documentation',
+      href: '/getting-started/llm-friendly-docs',
+    },
   ],
 }

sidebars/sidebarsDeveloperDocs.js

@@ -340,6 +340,11 @@ export default {
       value: '<hr/>',
       className: 'divider',
     },
+    {
+      type: 'link',
+      label: 'LLM Friendly Documentation',
+      href: '/getting-started/llm-friendly-docs',
+    },
     {
       type: 'category',
       label: 'Deprecated Products',

sidebars/sidebarsUserDocs.js

@@ -219,6 +219,11 @@ module.exports = {
       label: 'FAQ',
       id: 'guides/user-faq',
     },
+    {
+      type: 'doc',
+      label: 'LLM Friendly Documentation',
+      id: 'llm-friendly-docs',
+    },
     {
       type: 'link',
       label: 'Token and Contract Addresses →',