feat: add code source references and related page tagging; emits Rela…

src/components/overrides/Head.astro

@@ -4,8 +4,10 @@
  * and structured data (JSON-LD).
  * See ARCHITECTURE.md for details.
  */
+import { getCollection } from 'astro:content'
 import SiteScripts from '../SiteScripts.astro'
 import { baseSchemas } from '../../util/structured-data'
+import { relatedUserGuideFor } from '../../util/related-docs'
 
 const { head } = Astro.locals.starlightRoute
 const route = Astro.locals.starlightRoute
@@ -60,14 +62,55 @@ const breadcrumbItems = pathSegments.map((segment, i) => {
   }
 })
 
+// TechArticle node for docs pages with tags or sourceLinks. Reaches HTML-only
+// crawlers that don't follow the llms.txt convention.
+//
+// Schema reference for the fields used below:
+//   TechArticle:        https://schema.org/TechArticle
+//   keywords:           https://schema.org/keywords
+//   relatedLink:        https://schema.org/relatedLink
+//   isBasedOn:          https://schema.org/isBasedOn
+//   SoftwareSourceCode: https://schema.org/SoftwareSourceCode
+const entry = route.entry
+// Non-docs routes (blog authors/tags pages, etc.) flow through Starlight too
+// but their synthetic entry.data has no `tags` field — guard with ??.
+const tags = entry.data.tags ?? []
+const sourceLinks = entry.data.sourceLinks ?? []
+let techArticle: Record<string, unknown> | null = null
+if (tags.length > 0 || sourceLinks.length > 0) {
+  const related = tags.length > 0
+    ? relatedUserGuideFor(entry, await getCollection('docs'))
+    : []
+  techArticle = {
+    "@type": "TechArticle",
+    "headline": entry.data.title,
+    "url": siteUrl + Astro.url.pathname,
+    ...(tags.length > 0 ? { "keywords": tags.join(', ') } : {}),
+    ...(entry.data.description ? { "description": entry.data.description } : {}),
+    ...(related.length > 0
+      ? { "relatedLink": related.map((r) => siteUrl + '/' + r.slug + '/') }
+      : {}),
+    ...(sourceLinks.length > 0
+      ? {
+          "isBasedOn": sourceLinks.map((s: { repo: string, path: string }) => ({
+            "@type": "SoftwareSourceCode",
+            "codeRepository": `https://github.com/strands-agents/${s.repo}`,
+            "url": `https://github.com/strands-agents/${s.repo}/blob/main/${s.path}`,
+          })),
+        }
+      : {}),
+  }
+}
+
 const structuredData = {
   "@context": "https://schema.org",
   "@graph": [
     ...baseSchemas(siteUrl),
     {
       "@type": "BreadcrumbList",
       "itemListElement": breadcrumbItems
-    }
+    },
+    ...(techArticle ? [techArticle] : []),
   ]
 }
 ---

src/config/tags.ts

@@ -0,0 +1,25 @@
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
+import { z } from 'astro/zod'
+
+const TAGS_YML = fileURLToPath(new URL('./tags.yml', import.meta.url))
+
+function loadAllowedTags(): readonly string[] {
+  const raw = yaml.load(fs.readFileSync(TAGS_YML, 'utf-8'))
+  if (!Array.isArray(raw) || !raw.every((t): t is string => typeof t === 'string')) {
+    throw new Error(`[tags] ${TAGS_YML} must be a flat YAML list of strings`)
+  }
+  const deduped = Array.from(new Set(raw))
+  if (deduped.length !== raw.length) {
+    const dupes = raw.filter((t, i) => raw.indexOf(t) !== i)
+    throw new Error(`[tags] ${TAGS_YML} contains duplicate entries: ${[...new Set(dupes)].join(', ')}`)
+  }
+  return deduped
+}
+
+export const ALLOWED_TAGS = loadAllowedTags()
+
+export const TagSchema = z.enum(ALLOWED_TAGS as readonly [string, ...string[]])
+
+export type Tag = z.infer<typeof TagSchema>

src/config/tags.yml

@@ -0,0 +1,66 @@
+# Allowed tag vocabulary for user-guide pages. Drives the headless
+# "Related pages" block (in /<slug>/index.md, /llms-full.txt, and JSON-LD
+# `relatedLink`). Not surfaced on the rendered HTML — agent-facing only.
+# Validated by Zod (src/content.config.ts) — unknown tags fail the build.
+#
+# THE RULE: a tag means "this page TEACHES the named thing." Not "mentions
+# it" or "has a section labeled with it." If a reader landed on the page
+# looking to learn the tagged topic, they should leave understanding it.
+#
+# Common traps to avoid:
+# - Section heading matches tag name. A model provider with a "Streaming"
+#   section is not teaching streaming — the section says "yes, this
+#   provider supports it." Don't tag the provider page with `streaming`.
+# - Page mentions X in passing. References to other pages don't warrant
+#   tags. Tag for what the page IS, not what it links to.
+# - Lifecycle bloat. Words like "production" feel applicable to anything
+#   serious. We removed `production` for this reason — it labeled a
+#   property, not a topic.
+# - Over-tagging. 6+ tags dilutes the page's coordinates and makes it
+#   match too broadly. Aim for 2-4 tags that each name a primary topic.
+#
+# Authoring checklist:
+# 1. Does this page TEACH the tag? If not, leave it off.
+# 2. Would this page be a useful related-link for every other tag-mate?
+# 3. Is the tag a primary topic, or just mentioned? Tag only primaries.
+# 4. When in doubt, leave the tag off. Empty related-links beat misleading.
+#
+# Adding a new tag = PR editing this file. Every tag must apply to ≥2
+# pages and meaningfully bridge across sidebar sections.
+
+# Topics / domains — specific products, protocols, data types
+- agentcore
+- aws
+- bedrock
+- mcp
+- pii
+- vision
+
+# Capabilities — what the page teaches the reader to do
+- bidi-streaming
+- caching
+- conversation-management
+- error-handling
+- event-loop
+- failure-diagnosis
+- hooks
+- local-models
+- multi-agent
+- multimodal-evaluation
+- prompt-authoring
+- session-management
+- simulation
+- snapshots
+- state
+- streaming
+- structured-output
+- token-management
+- tool-authoring
+- tool-evaluation
+- tool-execution
+
+# Lifecycle / practice — where in the dev lifecycle this sits
+- deployment
+- observability
+- quickstart
+- safety

src/content.config.ts

@@ -6,6 +6,7 @@ import { docsSchema } from '@astrojs/starlight/schema'
 import { slug as githubSlug } from 'github-slugger'
 import { glob, file } from 'astro/loaders'
 import { normalizePathToSlug } from './util/links'
+import { TagSchema } from './config/tags'
 
 const authorSchema = z.object({
   name: z.string(),
@@ -14,6 +15,12 @@ const authorSchema = z.object({
   avatar: z.string().optional(),
 })
 
+export const sourceLinkSchema = z.object({
+  repo: z.enum(['sdk-python', 'sdk-typescript']),
+  path: z.string(),
+})
+export type SourceLink = z.infer<typeof sourceLinkSchema>
+
 const blogSchema = z.object({
   title: z.string(),
   date: z.coerce.date(),
@@ -89,6 +96,11 @@ export const collections = {
         description: z.string().optional(),
         // Array of slugs that should redirect to this page (e.g., old URLs)
         redirectFrom: z.array(z.string()).optional(),
+        // Tags from src/config/tags.yml — drive the build-time "Related pages" block
+        tags: z.array(TagSchema).default([]),
+        // Pointers to the SDK implementation behind this page. Rendered as an
+        // "Implementation" section on headless surfaces only (index.md, llms-full.txt).
+        sourceLinks: z.array(sourceLinkSchema).optional(),
       }),
     }),
   }),

src/content/docs/user-guide/build-with-ai.mdx

@@ -1,5 +1,6 @@
 ---
 title: Build with AI
+tags: [mcp, tool-authoring]
 description: Use AI coding assistants to build Strands Agents projects with up-to-date documentation context.
 redirectFrom:
   - docs/llms

src/content/docs/user-guide/concepts/agents/agent-loop.mdx

@@ -1,5 +1,6 @@
 ---
 title: Agent Loop
+tags: [event-loop, tool-execution, hooks]
 description: "How Strands agents reason, plan, and act. Understand the model-driven loop that orchestrates tool use, reflection, and goal completion."
 ---
 

src/content/docs/user-guide/concepts/agents/conversation-management.mdx

@@ -1,5 +1,6 @@
 ---
 title: Conversation Management
+tags: [conversation-management, session-management, token-management]
 ---
 
 In the Strands Agents SDK, context refers to the information provided to the agent for understanding and reasoning. This includes:

src/content/docs/user-guide/concepts/agents/hooks.mdx

@@ -1,6 +1,7 @@
 ---
 title: Hooks
 description: "Intercept and customize agent behavior at every step. Hooks let you add logging, validation, guardrails, and custom logic to the agent loop."
+tags: [hooks, event-loop, tool-execution]
 ---
 
 

src/content/docs/user-guide/concepts/agents/prompts.mdx

@@ -1,5 +1,6 @@
 ---
 title: Prompts
+tags: [safety, conversation-management, prompt-authoring]
 ---
 
 In the Strands Agents SDK, system prompts and user messages are the primary way to communicate with AI models. The SDK provides a flexible system for managing prompts, including both system prompts and user messages.

src/content/docs/user-guide/concepts/agents/retry-strategies.mdx

@@ -1,5 +1,6 @@
 ---
 title: Retry Strategies
+tags: [event-loop, error-handling]
 ---
 
 Model providers occasionally encounter errors such as rate limits, service unavailability, or network timeouts. By default, the agent retries `ModelThrottledException` failures automatically with exponential backoff and the `Angent.retry_strategy` parameter lets you customize this behavior.

src/content/docs/user-guide/concepts/agents/session-management.mdx

@@ -1,6 +1,7 @@
 ---
 title: Session Management
 description: "Persist agent conversations across sessions. Save and restore chat history, tool state, and context for long-running AI workflows."
+tags: [session-management, snapshots, state]
 ---
 
 Session management in Strands Agents provides a robust mechanism for persisting agent state and conversation history across multiple interactions. This enables agents to maintain context and continuity even when the application restarts or when deployed in distributed environments.

src/content/docs/user-guide/concepts/agents/state.mdx

@@ -2,6 +2,7 @@
 title: State Management
 sidebar:
   label: "State"
+tags: [state, snapshots, session-management]
 ---
 
 Strands Agents state is maintained in several forms:

src/content/docs/user-guide/concepts/agents/structured-output.mdx

@@ -1,6 +1,7 @@
 ---
 title: Structured Output
 description: "Get typed, validated responses from AI agents. Define Pydantic models and Strands returns structured data instead of raw text."
+tags: [structured-output]
 ---
 
 ## Introduction

src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx

@@ -1,6 +1,7 @@
 ---
 title: BidiAgent
 experimental: true
+tags: [bidi-streaming]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx

@@ -1,6 +1,7 @@
 ---
 title: Events
 experimental: true
+tags: [bidi-streaming]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx

@@ -1,6 +1,9 @@
 ---
-title: Hooks
+title: Bidirectional Streaming Hooks
+sidebar:
+  label: "Hooks"
 experimental: true
+tags: [bidi-streaming, hooks]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx

@@ -1,6 +1,7 @@
 ---
 title: Interruptions
 experimental: true
+tags: [bidi-streaming]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx

@@ -3,6 +3,7 @@ title: I/O Channels
 experimental: true
 sidebar:
   label: "IO"
+tags: [bidi-streaming]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx

@@ -1,6 +1,7 @@
 ---
 title: Gemini Live
 experimental: true
+tags: [bidi-streaming]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx

@@ -1,6 +1,7 @@
 ---
 title: Nova Sonic
 experimental: true
+tags: [bidi-streaming, aws, bedrock]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx

@@ -1,6 +1,7 @@
 ---
 title: OpenAI Realtime
 experimental: true
+tags: [bidi-streaming]
 ---
 
 

src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx

@@ -1,5 +1,6 @@
 ---
 title: Quickstart
+tags: [bidi-streaming, quickstart]
 description: "Build voice-enabled AI agents with real-time audio streaming. Works with Amazon Nova Sonic, Gemini Live, and OpenAI Realtime."
 experimental: true
 ---

src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx

@@ -1,6 +1,9 @@
 ---
-title: Session Management
+title: Bidirectional Streaming Session Management
+sidebar:
+  label: "Session Management"
 experimental: true
+tags: [bidi-streaming, session-management, snapshots]
 ---
 
 

src/content/docs/user-guide/concepts/experimental/agent-config.mdx

@@ -1,5 +1,6 @@
 ---
 title: Agent Configuration
+tags: [tool-authoring, bedrock, prompt-authoring]
 experimental: true
 sidebar:
   label: "AgentConfig"

src/content/docs/user-guide/concepts/interrupts.mdx

@@ -1,5 +1,6 @@
 ---
 title: Interrupts
+tags: [event-loop, hooks, tool-execution, error-handling]
 description: "Pause AI agents mid-execution for human approval, input, or review. Build human-in-the-loop workflows with interrupt and resume patterns."
 ---
 

src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx

@@ -1,6 +1,7 @@
 ---
 title: Amazon Bedrock
 integrationType: model-provider
+tags: [bedrock, aws, vision, safety, caching]
 ---
 
 Amazon Bedrock is a fully managed service that offers a choice of high-performing foundation models from leading AI companies through a unified API. Strands provides native support for Amazon Bedrock, allowing you to use these powerful models in your agents with minimal configuration.

src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx

@@ -2,6 +2,7 @@
 title: Amazon Nova
 languages: Python
 integrationType: model-provider
+tags: [bedrock, aws, vision]
 ---
 
 [Amazon Nova](https://nova.amazon.com/) is a new generation of foundation models with frontier intelligence and industry leading price performance. Generate text, code, and images with natural language prompts. The [`strands-amazon-nova`](https://pypi.org/project/strands-amazon-nova/) package ([GitHub](https://github.com/amazon-nova-api/strands-nova)) provides an integration for the Strands Agents SDK, enabling seamless use of Amazon Nova models.

src/content/docs/user-guide/concepts/model-providers/anthropic.mdx

@@ -1,5 +1,6 @@
 ---
 title: Anthropic
+tags: [structured-output, caching]
 integrationType: model-provider
 ---
 

src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx

@@ -1,5 +1,6 @@
 ---
 title: Creating a Custom Model Provider
+tags: [tool-execution]
 sidebar:
   label: "Custom Providers"
 integrationType: model-provider

src/content/docs/user-guide/concepts/model-providers/google.mdx

@@ -1,5 +1,6 @@
 ---
 title: Google
+tags: [vision]
 integrationType: model-provider
 redirectFrom:
   - docs/user-guide/concepts/model-providers/gemini