Update docs to match llms.json schema

- llms.txt: Remove outdated AI Index section, add LLMs Index section with correct properties/links/embedded, fix common query examples - reference.md: Add AI Index as recommended entry point, add schema example with latest_patches and latest_security_month collections - metrics.md: Split overview to separate file, add critical CVE queries, update llms-index examples to use latest-security link on latest_patches 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-19 18:06:02 -05:00 · 2025-12-10 16:57:04 -08:00
parent e9473802a7
commit e17ce1598a
3 changed files with 121 additions and 45 deletions
--- a/llms.txt
+++ b/llms.txt
@@ -34,31 +34,6 @@ Reference:
 * `latest` and `latest_lts` reference supported (not preview) releases
 * **Discover available links**: `jq '._links | keys[]'` on any resource reveals all navigation options

-## AI Index
-
-The AI Index (`llms.json`) provides direct access to the most common data points without navigation:
-
-**Properties** — answer simple queries immediately:
-
-* `latest`, `latest_lts` — current supported major versions
-* `latest_patch`, `latest_lts_patch` — current patch versions
-* `latest_year`, `latest_security_month` — timeline coordinates
-* `supported_releases` — array of supported version strings
-
-**Links** — single-hop to detailed data:
-
-* `latest-patch`, `latest-lts-patch` — jump to patch index
-* `latest-year`, `latest-security-month` — jump into timeline
-* `releases-index`, `timeline-index` — full indexes when needed
-
-**Embedded** — filtered subset for common queries:
-
-* `_embedded.supported_releases[]` — supported versions with `release_type` and links
-
-**Example:** "What's the latest .NET patch?" → read `latest_patch` property directly (0 additional fetches).
-
-**Example:** "CVEs since October?" → follow `latest-security-month` link (1 fetch to reach security month, then walk `prev-security`).
-
 ## Do first

 1. Start with the **AI Index** (`llms.json`) — it may answer the query directly or provide a shortcut link
@@ -95,10 +70,8 @@ Total: 4 fetches (1 index + 3 security months)

 **"What patch should I install for .NET X?"** — Version lookup:

-1. If X is `latest` or `latest_lts`: read `latest_patch` or `latest_lts_patch` from AI Index (1 fetch)
-2. Otherwise: AI Index → `releases-index` → version index (e.g., `8.0/index.json`)
-3. Check `latest_security` property for current security patch version
-4. If user needs CVE details, follow `_links["latest-security"]` to patch index
+1. Filter `_embedded.latest_patches[]` by `release == "X"`, read `version` (1 fetch)
+2. If user needs CVE details, follow `latest-security` link to patch index

 **"Any critical CVEs this month?"** — Direct month lookup:

@@ -107,19 +80,50 @@ Total: 4 fetches (1 index + 3 security months)

 **Expected fetch counts** (for self-assessment):

-* "Latest patch for .NET": 1 fetch (AI Index)
-* "Latest patch for .NET X": 2–3 fetches (AI Index → version index)
+* "Latest patch for .NET 9": 1 fetch (AI Index → `_embedded.latest_patches[]`)
+* "CVEs in latest security month for .NET 8": 1 fetch (AI Index → `_embedded.latest_security_month[]`)
 * "CVEs since [date]": 1 + number of security months in range
+* "Critical CVEs for .NET 8 over 6 months": 1 + number of security patches (AI Index → `latest-security` link → walk `prev-security`)
 * "CVEs for specific patch": 2–3 fetches

 If your count significantly exceeds these, you may be navigating inefficiently.

+## LLMs Index
+
+Optimized for AI assistants. Covers supported versions only with common query results pre-embedded.
+
+**Properties:**
+
+* `latest`, `latest_lts` — current supported major versions
+* `latest_year` — current year for timeline navigation
+* `releases` — supported version strings `["10.0", "9.0", "8.0"]`
+
+**Links:**
+
+* `latest`, `latest-lts` — jump to major version index
+* `latest-month`, `latest-security-month` — jump into timeline
+* `latest-year` — jump to year index
+* `releases-index`, `timeline-index` — full indexes when needed
+
+**Embedded:**
+
+* `_embedded.latest_patches[]` — latest patch per version with `release`, `version`, `security`, `cve_count`, `sdk_version`, `self` link to patch index, and `latest-security` link to security patch index
+* `_embedded.latest_security_month[]` — security status per version with `cve_records[]` and `self` link to month index
+
+**Examples:**
+
+* "Latest .NET 9 patch?" → filter `_embedded.latest_patches[]` by `release == "9.0"`, read `version` (1 fetch)
+* "CVEs since October?" → follow `latest-security-month` link, walk `prev-security` (1 + n fetches)
+* "Critical CVEs for .NET 8 over 6 months?" → filter `_embedded.latest_patches[]` by `release == "8.0"`, follow `latest-security` link, walk `prev-security` (1 + n fetches)
+
+Use this as your starting point. Navigate to Releases Index or Timeline Index via links when you need full history or unsupported versions.
+
 ## Releases Index

 All major versions with full history. Navigate here via `releases-index` link.

 * `latest`, `latest_lts` — current supported versions
-* `_embedded.releases[]` — all major versions (newest first)
+* `_embedded.releases[]` — all major versions (newest first), including EOL versions
 * Each release has: `version`, `release_type`, `supported`, `eol_date`

 ## Timeline Index
--- a/llms/reference.md
+++ b/llms/reference.md
@@ -8,9 +8,12 @@ For quick reference, see [llms.txt](https://raw.githubusercontent.com/dotnet/cor

 | Query Type | Entry Point |
 |------------|-------------|
+| **AI Index (recommended)** | `https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/llms.json` |
 | Single-version queries | `https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/index.json` |
 | Time-range queries | `https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/index.json` |

+The **AI Index** is the best starting point — it combines key properties and links from both indexes, with embedded data for common queries.
+
 **CRITICAL**: Never construct URLs manually. Always follow `_links["..."].href` values from JSON responses.

 Reference:
@@ -22,14 +25,17 @@ Reference:

 | Task | Path |
 |------|------|
-| Latest release | `index.json` → `_links["latest"].href` |
-| Latest LTS | `index.json` → `_links["latest-lts"].href` |
+| Latest patch for .NET 9 | `llms.json` → `_embedded.latest_patches[]` where `release == "9.0"` |
+| CVEs in latest security month | `llms.json` → `_embedded.latest_security_month[]` |
+| Critical CVEs for .NET 8 over time | `llms.json` → `_embedded.latest_security_month[]` where `release == "8.0"` → `_links["latest-security"]` → walk `prev-security` |
+| Latest release | `llms.json` → `_links["latest"].href` |
+| Latest LTS | `llms.json` → `_links["latest-lts"].href` |
 | Version patches | `index.json` → version → `_embedded.releases[]` |
 | Security patches | `10.0/index.json` → `_links["latest-security"].href` |
 | CVEs for version | `10.0/index.json` → `_embedded.releases[]` where `security: true` |
 | CVEs for patch | `10.0/10.0.1/index.json` → `_embedded.disclosures[]` |
 | CVEs by month | `timeline/index.json` → year → month → `_embedded.disclosures[]` |
-| **CVEs since date** | `timeline/index.json` → `latest-year` → `latest-security-month` → follow `prev-security` until target date → filter by `affected_releases` |
+| **CVEs since date** | `llms.json` → `_links["latest-security-month"]` → follow `prev-security` until target date → filter by `affected_releases` |
 | Breaking changes | `10.0/index.json` → `_links["compatibility-json"].href` |
 | SDK downloads | `10.0/sdk/index.json` |
 | OS support | `10.0/manifest.json` → `_links["supported-os-json"].href` |
@@ -61,6 +67,13 @@ Example output for a patch index:

 ### Link Relations by Resource Type

+**AI index** (`llms.json`):
+- `latest`, `latest-lts` — jump to major version index
+- `latest-month`, `latest-security-month` — jump to timeline month
+- `latest-year` — jump to year index
+- `releases-index`, `timeline-index` — full indexes
+- `llms-txt` — AI navigation guide
+
 **Root index** (`index.json`):
 - `latest`, `latest-lts` — jump to current releases
 - `timeline-index` — switch to time-based navigation
@@ -92,6 +105,71 @@ Link relation names are self-documenting:

 ## Schema Examples

+### AI Index (`llms.json`)
+
+```json
+{
+  "kind": "llms-index",
+  "title": ".NET Release Index for AI",
+  "latest": "10.0",
+  "latest_lts": "10.0",
+  "latest_year": "2025",
+  "releases": ["10.0", "9.0", "8.0"],
+  "_links": {
+    "self": { "href": ".../llms.json" },
+    "latest": { "href": ".../10.0/index.json", "title": ".NET 10.0" },
+    "latest-lts": { "href": ".../10.0/index.json", "title": ".NET 10.0 (LTS)" },
+    "latest-month": { "href": ".../timeline/2025/12/index.json", "title": "2025-12" },
+    "latest-security-month": { "href": ".../timeline/2025/10/index.json", "title": "2025-10" },
+    "latest-year": { "href": ".../timeline/2025/index.json", "title": "2025" },
+    "releases-index": { "href": ".../index.json" },
+    "timeline-index": { "href": ".../timeline/index.json" },
+    "llms-txt": { "href": ".../llms.txt", "type": "text/plain" }
+  },
+  "_embedded": {
+    "latest_patches": [
+      {
+        "version": "10.0.1",
+        "release": "10.0",
+        "release_type": "lts",
+        "date": "2025-12-09T00:00:00+00:00",
+        "year": "2025",
+        "month": "12",
+        "security": false,
+        "cve_count": 0,
+        "support_phase": "active",
+        "sdk_version": "10.0.101",
+        "_links": {
+          "self": { "href": ".../10.0/10.0.1/index.json" },
+          "latest-security": { "href": ".../10.0/10.0.0/index.json" }
+        }
+      }
+    ],
+    "latest_security_month": [
+      {
+        "release": "8.0",
+        "release_type": "lts",
+        "version": "8.0.21",
+        "sdk_version": "8.0.415",
+        "year": "2025",
+        "month": "10",
+        "security": true,
+        "cve_count": 3,
+        "cve_records": ["CVE-2025-55247", "CVE-2025-55248", "CVE-2025-55315"],
+        "_links": {
+          "self": { "href": ".../timeline/2025/10/index.json" }
+        }
+      }
+    ]
+  }
+}
+```
+
+**Key embedded collections:**
+
+- `_embedded.latest_patches[]` — Latest patch per supported version. Filter by `release` (e.g., `select(.release == "9.0")`). The `self` link points to the patch index; the `latest-security` link jumps to the security patch index for `prev-security` traversal.
+- `_embedded.latest_security_month[]` — Security status per version for the latest security month. Includes `cve_records[]` inline. The `self` link points to the month index.
+
 ### Releases Index (`index.json`)

 ```json
--- a/release-notes/queries/metrics.md
+++ b/release-notes/queries/metrics.md
@@ -567,19 +567,13 @@ done
 # 8.0.12 | CVE-2025-21172: .NET Remote Code Execution Vulnerability
 ```

-**llms-index:** Uses `_embedded.latest_security_month` to find the starting point, then navigates to version-specific patches:
+**llms-index:** Uses `_embedded.latest_patches` with `latest-security` link for direct access:

 ```bash
 LLMS="https://raw.githubusercontent.com/dotnet/core/release-index/release-notes/llms.json"

-# Get the 8.0 patch from latest_security_month, then follow to version index
-PATCH_DATA=$(curl -s "$LLMS" | jq -r '._embedded.latest_security_month[] | select(.release == "8.0")')
-VERSION_HREF=$(curl -s "$LLMS" | jq -r '._embedded.latest_patches[] | select(.release == "8.0") | ._links.self.href' | sed 's|/8.0.[0-9]*/|/|')/../index.json
-
-# Alternative: navigate via releases-index link to 8.0/index.json
-VERSION_HREF=$(curl -s "$LLMS" | jq -r '._links["releases-index"].href')
-VERSION_HREF=$(curl -s "$VERSION_HREF" | jq -r '._embedded.releases[] | select(.version == "8.0") | ._links.self.href')
-PATCH_HREF=$(curl -s "$VERSION_HREF" | jq -r '._links["latest-security"].href')
+# Direct jump to 8.0's latest security patch via latest-security link
+PATCH_HREF=$(curl -s "$LLMS" | jq -r '._embedded.latest_patches[] | select(.release == "8.0") | ._links["latest-security"].href')

 # Walk back security patches for 8.0
 for i in {1..6}; do
@@ -601,7 +595,7 @@ done
 - **The `release` property:** Patch entries include a `release` property (e.g., `"release": "8.0"`) that enables filtering by major version. This is what makes `select(.release == "8.0")` work on embedded patch collections like `_embedded.latest_patches[]` or `_embedded.latest_security_month[]`.
 - **Use case:** Version-specific security audits ("Is my .NET 8 deployment exposed to any critical vulnerabilities?").

-**Winner:** hal-index (**24x smaller**, releases-index cannot answer this query); llms-index requires extra navigation (no direct 8.0 shortcut in embedded data)
+**Winner:** hal-index (**24x smaller**, releases-index cannot answer this query); llms-index is 10% smaller (50 KB vs 55 KB) with direct `latest-security` link

 ### Breaking Changes Summary