Add usage guidance to llms.txt for LLM content discovery (#59849)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/frame/middleware/llms-txt.ts

@@ -53,13 +53,17 @@ function generateBasicLlmsTxt(): string {
 
 > Help for wherever you are on your GitHub journey.
 
-## Docs Content
+## How to Use
 
-- [Page List API](${BASE_API_URL}/en/free-pro-team@latest)
-- [Versions API](${BASE_API_URL}/versions): \`curl "https://docs.github.com/api/pagelist/versions"\`
-- [Languages API](${BASE_API_URL}/languages): \`curl "https://docs.github.com/api/pagelist/languages"\`
-- [Article API](https://docs.github.com/api/article): \`curl "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"\`
-- [Search API](https://docs.github.com/api/search): \`curl "https://docs.github.com/api/search?query=actions&language=en&version=free-pro-team@latest"\`
+To find a specific article, use the **Search API** with a query. To browse all available pages, use the **Page List API** to get a list of paths, then fetch individual articles with the **Article API**. The \`/api/article/body\` endpoint returns clean markdown, ideal for LLM consumption.
+
+## APIs
+
+- [Page List API](${BASE_API_URL}/en/free-pro-team@latest): Returns all article paths for a given version. Use this to discover what content is available.
+- [Article API](https://docs.github.com/api/article): Fetches a single article as JSON (metadata and markdown body). Use \`/api/article/body\` for markdown only. Example: \`/api/article/body?pathname=/en/get-started/start-your-journey/about-github-and-git\`
+- [Search API](https://docs.github.com/api/search/v1): Full-text search across all articles. Returns matching pages with context. Example: \`/api/search/v1?query=actions&language=en&version=free-pro-team@latest&client_name=curl\`
+- [Versions API](${BASE_API_URL}/versions): Lists all available documentation versions.
+- [Languages API](${BASE_API_URL}/languages): Lists all available languages.
 
 ## Translations
 

src/frame/tests/llms-txt.ts

@@ -20,13 +20,25 @@ describe('llms.txt endpoint', () => {
     expect(content).toMatch(/^# .*GitHub.*Docs/m)
   })
 
+  test('includes how to use guidance', async () => {
+    const res = await get('/llms.txt')
+    const content = res.body
+
+    // Should explain the workflow for LLMs
+    expect(content).toMatch(/Search API/)
+    expect(content).toMatch(/Page List API/)
+    expect(content).toMatch(/Article API/)
+    expect(content).toMatch(/markdown/i)
+  })
+
   test('includes programmatic access section', async () => {
     const res = await get('/llms.txt')
     const content = res.body
 
     // Should mention the existing APIs
     expect(content).toMatch(/Article API/i)
     expect(content).toMatch(/Page List API/i)
+    expect(content).toMatch(/Search API/i)
     expect(content).toMatch(/api\/article/i)
     expect(content).toMatch(/api\/pagelist\/en\/free-pro-team@latest/i)
   })
@@ -36,7 +48,8 @@ describe('llms.txt endpoint', () => {
     const content = res.body
 
     // Should have all the main sections we expect
-    expect(content).toMatch(/## Docs Content/i)
+    expect(content).toMatch(/## How to Use/i)
+    expect(content).toMatch(/## APIs/i)
     expect(content).toMatch(/## Translations/i)
     expect(content).toMatch(/## Versions/i)
   })
@@ -75,7 +88,6 @@ describe('llms.txt endpoint', () => {
 
     // Should prominently feature the pagelist API as the main content source
     expect(content).toMatch(/Page List API.*api\/pagelist\/en\/free-pro-team@latest/i)
-    expect(content).not.toMatch(/Machine-readable list/i) // Removed descriptions
   })
 
   test.each(['free-pro-team@latest', 'enterprise-cloud@latest'])(
@@ -100,7 +112,7 @@ describe('llms.txt endpoint', () => {
     expect(content).toMatch(/api\/pagelist\/en\/enterprise-server@\d+\.\d+/)
   })
 
-  test('follows llms.txt specification structure and has reasonable length', async () => {
+  test('follows llms.txt specification structure', async () => {
     const res = await get('/llms.txt')
     const content = res.body
 
@@ -116,10 +128,6 @@ describe('llms.txt endpoint', () => {
     // Check for markdown links
     expect(content).toMatch(/\[.+\]\(.+\)/m)
 
-    // Should include translations and versions but still be reasonable
-    expect(content.length).toBeGreaterThan(500)
-    expect(content.length).toBeLessThan(5000)
-
     // Split into lines for structure analysis
     const lines = content.split('\n')
 
@@ -131,8 +139,8 @@ describe('llms.txt endpoint', () => {
     const hasBlockquote = lines.some((line: string) => line.trim().startsWith('>'))
     expect(hasBlockquote).toBe(true)
 
-    // Should have multiple H2 sections (Docs Content, Translations, Versions)
+    // Should have multiple H2 sections (How to Use, APIs, Translations, Versions)
     const h2Sections = lines.filter((line: string) => line.trim().startsWith('## '))
-    expect(h2Sections.length).toBeGreaterThanOrEqual(3)
+    expect(h2Sections.length).toBeGreaterThanOrEqual(4)
   })
 })