From b2b16e18d68eba0f963010ade9c4be98a324e34c Mon Sep 17 00:00:00 2001
From: Richard Lander <rlander@microsoft.com>
Date: Mon, 8 Dec 2025 16:21:30 -0800
Subject: [PATCH] Add Year Index schema and fix navigation paths in
 reference.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Common Workflows table: updated CVEs since date path to show latest-year
- Timeline Index schema: added latest-year link
- Added new Year Index schema example showing latest-security-month link
  (this is the crucial intermediate step in the navigation)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 llms/reference.md | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/llms/reference.md b/llms/reference.md
index 9a9fa1497..b35bca1df 100644
--- a/llms/reference.md
+++ b/llms/reference.md
@@ -29,7 +29,7 @@ Reference:
 | 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` → year → `latest-security-month` → follow `prev-security` until target date → filter `_embedded.disclosures[]` by `affected_releases` |
+| **CVEs since date** | `timeline/index.json` → `latest-year` → `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` |
@@ -227,6 +227,7 @@ Link relation names are self-documenting:
   "latest_year": "2025",
   "_links": {
     "self": { "href": ".../timeline/index.json" },
+    "latest-year": { "href": ".../timeline/2025/index.json" },
     "releases-index": { "href": ".../index.json" }
   },
   "_embedded": {
@@ -243,6 +244,36 @@ Link relation names are self-documenting:
 }
 ```
 
+### Year Index (`timeline/2025/index.json`)
+
+```json
+{
+  "kind": "year-index",
+  "year": "2025",
+  "latest_month": "11",
+  "latest_security_month": "10",
+  "_links": {
+    "self": { "href": ".../timeline/2025/index.json" },
+    "prev": { "href": ".../timeline/2024/index.json" },
+    "latest-month": { "href": ".../timeline/2025/11/index.json" },
+    "latest-security-month": { "href": ".../timeline/2025/10/index.json" },
+    "timeline-index": { "href": ".../timeline/index.json" }
+  },
+  "_embedded": {
+    "months": [
+      {
+        "month": "10",
+        "security": true,
+        "cve_count": 3,
+        "_links": {
+          "self": { "href": ".../timeline/2025/10/index.json" }
+        }
+      }
+    ]
+  }
+}
+```
+
 ### Month Index (`timeline/2025/01/index.json`)
 
 ```json