From c55864957ce805d42e60c8ea62fd7229cfde6efb Mon Sep 17 00:00:00 2001
From: Matej Minar <matej@minar.dev>
Date: Thu, 21 May 2026 12:08:24 +0200
Subject: [PATCH] feat(docs): Render additional_context in attribute cards and
 LLM export

Surfaces the `additional_context` field (added in #393, populated in #397) in
the Astro docs site and the plain text LLM export.

Changes:

- content.config.ts: Added additional_context to the Zod schema
- AttributeCard.astro: Renders notes as a collapsible section (open by default)
  above the changelog, matching the existing disclosure pattern
- llms-full.txt.ts: Includes additional_context as nested list items in the
  plain text export for LLM consumption
---
 docs/src/components/AttributeCard.astro | 16 ++++++++++++++++
 docs/src/content.config.ts              |  1 +
 docs/src/pages/llms-full.txt.ts         |  7 +++++++
 3 files changed, 24 insertions(+)

diff --git a/docs/src/components/AttributeCard.astro b/docs/src/components/AttributeCard.astro
index 6550f9ce..5dea76c2 100644
--- a/docs/src/components/AttributeCard.astro
+++ b/docs/src/components/AttributeCard.astro
@@ -116,6 +116,22 @@ const rawJson = JSON.stringify(attribute, null, 2);
     )}
   </div>
   
+  {attribute.additional_context && attribute.additional_context.length > 0 && (
+    <details open class="mt-4 pt-3 border-t border-border group">
+      <summary class="cursor-pointer list-none flex items-center gap-2 text-sm text-text-muted transition-colors duration-fast hover:text-text-secondary">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="transition-transform duration-fast group-open:rotate-90">
+          <path d="M9 18l6-6-6-6"/>
+        </svg>
+        Additional Context
+      </summary>
+      <ul class="mt-3 ml-5 flex flex-col gap-1.5 list-disc list-outside text-sm text-text-secondary leading-relaxed">
+        {attribute.additional_context.map((note) => (
+          <li>{note}</li>
+        ))}
+      </ul>
+    </details>
+  )}
+
   {attribute.changelog && attribute.changelog.length > 0 && (
     <details class="mt-4 pt-3 border-t border-border group">
       <summary class="cursor-pointer list-none flex items-center gap-2 text-sm text-text-muted transition-colors duration-fast hover:text-text-secondary">
diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts
index 6e59c52f..da1b2be3 100644
--- a/docs/src/content.config.ts
+++ b/docs/src/content.config.ts
@@ -26,6 +26,7 @@ const attributeSchema = z.object({
     .optional(),
   alias: z.array(z.string()).optional(),
   sdks: z.array(z.string()).optional(),
+  additional_context: z.array(z.string()).optional(),
   changelog: z
     .array(
       z.object({
diff --git a/docs/src/pages/llms-full.txt.ts b/docs/src/pages/llms-full.txt.ts
index bbacc643..63e2b8cf 100644
--- a/docs/src/pages/llms-full.txt.ts
+++ b/docs/src/pages/llms-full.txt.ts
@@ -74,6 +74,13 @@ export const GET: APIRoute = async () => {
         lines.push('- OpenTelemetry: yes');
       }
 
+      if (data.additional_context && data.additional_context.length > 0) {
+        lines.push('- Additional context:');
+        for (const note of data.additional_context) {
+          lines.push(`  - ${note}`);
+        }
+      }
+
       if (data.deprecation) {
         let deprecationNote = '- Deprecated: yes';
         if (data.deprecation.replacement) {