Dev to main, 7th July, 2026

src/components/Sidebar.astro

@@ -10,6 +10,7 @@ import { tabNavigation, getActiveTab, getActiveGroup, type NavItem, type NavGrou
 const currentPath = Astro.url.pathname;
 const activeTab = getActiveTab(currentPath);
 const isDocsTab = activeTab?.tab === 'Docs';
+const isSdkTab = activeTab?.tab === 'SDK';
 
 // For Docs tab: groups are sections you switch between
 // For other tabs: groups are also switchable sections
@@ -21,14 +22,23 @@ let activeGroup: NavGroup | undefined;
 if (isDocsTab) {
   activeGroup = getActiveGroup(currentPath);
 } else {
-  // For non-Docs tabs, find the group containing current page
-  activeGroup = allGroups.find(g =>
-    g.items.some(item => {
-      const norm = currentPath.replace(/\/$/, '') || '/';
-      const href = (item.href || '').replace(/\/$/, '') || '/';
-      return href === norm || (href !== '/' && norm.startsWith(href + '/'));
-    })
-  ) || allGroups[0];
+  // For non-Docs tabs, pick the group whose deepest matching item href is the
+  // longest (most specific), so a broad landing group (e.g. SDK Overview at
+  // /docs/sdk) never shadows a product group like Evaluation (/docs/sdk/evals).
+  const norm = currentPath.replace(/\/$/, '') || '/';
+  let bestLen = -1;
+  const consider = (g: NavGroup, list: NavItem[]) => {
+    for (const it of list) {
+      if (it.href) {
+        const href = it.href.replace(/\/$/, '') || '/';
+        const matches = href === norm || (href !== '/' && href !== '/docs' && norm.startsWith(href + '/'));
+        if (matches && href.length > bestLen) { bestLen = href.length; activeGroup = g; }
+      }
+      if (it.items) consider(g, it.items);
+    }
+  };
+  allGroups.forEach(g => consider(g, g.items));
+  if (!activeGroup) activeGroup = allGroups[0];
 }
 
 const items = activeGroup?.items || [];
@@ -127,6 +137,22 @@ const referenceItems: DropdownItem[] = [
   { title: 'API Reference', icon: 'webhook', href: '/docs/api' },
 ];
 
+// SDK tab: the same phase-grouped product dropdown as Docs, with the SDK's products.
+const sdkPhasedOrder: { phase: string; titles: string[] }[] = [
+  { phase: 'Start',              titles: ['SDK Overview'] },
+  { phase: 'Observe & diagnose', titles: ['traceAI'] },
+  { phase: 'Evaluate & measure', titles: ['Evaluation', 'Simulation', 'Datasets'] },
+  { phase: 'Improve',            titles: ['Prompt Optimization', 'Annotation Queues'] },
+  { phase: 'Build & connect',    titles: ['Knowledge Base'] },
+  { phase: 'Protect',            titles: ['Protect'] },
+];
+const sdkReferenceItems: DropdownItem[] = [
+  { title: 'Product Docs', icon: 'book', href: '/docs' },
+  { title: 'Integrations', icon: 'plug', href: '/docs/integrations' },
+  { title: 'Guides', icon: 'compass', href: '/docs/cookbook' },
+  { title: 'API Reference', icon: 'webhook', href: '/docs/api' },
+];
+
 let dropdownSections: DropdownSection[];
 if (isDocsTab) {
   dropdownSections = phasedOrder
@@ -140,6 +166,17 @@ if (isDocsTab) {
   if (leftovers.length) dropdownSections.push({ phase: 'More', items: leftovers });
 
   dropdownSections.push({ phase: 'Reference', items: referenceItems });
+} else if (isSdkTab) {
+  dropdownSections = sdkPhasedOrder
+    .map(p => ({ phase: p.phase, items: p.titles.filter(t => groupLookup.has(t)).map(toItem) }))
+    .filter(s => s.items.length > 0);
+
+  // Future-proofing: any SDK group not placed above still shows under "More".
+  const placed = new Set<string>(sdkPhasedOrder.flatMap(p => p.titles));
+  const leftovers = allGroups.map(g => g.group).filter(t => !placed.has(t)).map(toItem);
+  if (leftovers.length) dropdownSections.push({ phase: 'More', items: leftovers });
+
+  dropdownSections.push({ phase: 'Reference', items: sdkReferenceItems });
 } else {
   // Other multi-group tabs: one unlabelled section (empty phase hides the header).
   dropdownSections = [{ phase: '', items: allGroups.map(g => toItem(g.group)) }];

src/lib/redirects.ts

@@ -1,7 +1,27 @@
 // Auto-generated redirect map: old Mintlify URLs → new docs URLs
 // 275 redirects from futureagi.mintlify.app
 export const redirectMap: Record<string, string> = {
+  // Manual-instrumentation pages moved from Observe features into the traceAI SDK section
+  '/docs/observe/features/manual-tracing/set-up-tracing': '/docs/sdk/tracing/set-up-tracing',
+  '/docs/observe/features/manual-tracing/instrument-with-traceai-helpers': '/docs/sdk/tracing/instrument-with-traceai-helpers',
+  '/docs/observe/features/manual-tracing/set-session-user-id': '/docs/sdk/tracing/set-session-user-id',
+  '/docs/observe/features/manual-tracing/add-attributes-metadata-tags': '/docs/sdk/tracing/add-attributes-metadata-tags',
+  '/docs/observe/features/manual-tracing/log-prompt-templates': '/docs/sdk/tracing/log-prompt-templates',
+  '/docs/observe/features/manual-tracing/add-events-exceptions-status': '/docs/sdk/tracing/add-events-exceptions-status',
+  '/docs/observe/features/manual-tracing/mask-span-attributes': '/docs/sdk/tracing/mask-span-attributes',
+  '/docs/observe/features/manual-tracing/create-tool-spans': '/docs/sdk/tracing/create-tool-spans',
+  '/docs/observe/features/manual-tracing/get-current-span-context': '/docs/sdk/tracing/get-current-span-context',
+  '/docs/observe/features/manual-tracing/in-line-evals': '/docs/sdk/tracing/in-line-evals',
+  '/docs/observe/features/manual-tracing/annotating-using-api': '/docs/sdk/tracing/annotating-using-api',
+  '/docs/observe/features/manual-tracing/semantic-conventions': '/docs/sdk/tracing/semantic-conventions',
+  '/docs/observe/features/manual-tracing/advanced-tracing-examples': '/docs/sdk/tracing/advanced-tracing-examples',
+  '/docs/observe/features/manual-tracing/langfuse-integration': '/docs/sdk/tracing/langfuse-integration',
+  '/docs/cookbook/observability': '/docs/cookbook/observe-langgraph-agent-and-obtain-insights',
+  '/docs/cookbook/improve-langgraph-agent-with-observability': '/docs/cookbook/observe-langgraph-agent-and-obtain-insights',
   '/docs/observe/features/annotation-queue-using-sdk': '/docs/annotations/sdk/annotation-queue-using-sdk',
+  // SDK pages restructured: sdk/tracing.mdx flat page → sdk/tracing/ folder (index still serves /docs/sdk/tracing); annotation-queues moved under Annotations
+  '/docs/sdk/tracing': '/docs/sdk/tracing/set-up-tracing',
+  '/docs/sdk/annotation-queues': '/docs/annotations/sdk/annotation-queue-using-sdk',
   '/docs/observe/voice/set-up': '/docs/observe/features/voice',
   '/docs/quickstart/installation': '/docs/installation',
   '/docs/observability': '/docs/tracing/auto',
@@ -14,17 +34,17 @@ export const redirectMap: Record<string, string> = {
   '/docs/knowledge-base/concept': '/docs/knowledge-base/concepts/concept',
   '/docs/prompt-workbench': '/docs/prompt',
   '/docs/prompt-workbench/sdk': '/docs/prompt/features/sdk',
-  '/docs/tracing/manual/log-prompt-templates': '/docs/observe/features/manual-tracing/log-prompt-templates',
-  '/docs/tracing/manual/in-line-evals': '/docs/observe/features/manual-tracing/in-line-evals',
+  '/docs/tracing/manual/log-prompt-templates': '/docs/sdk/tracing/log-prompt-templates',
+  '/docs/tracing/manual/in-line-evals': '/docs/sdk/tracing/in-line-evals',
   '/docs/simulation/set-up/scenarios': '/docs/simulation/concepts/scenarios',
   '/docs/simulation/set-up/agent-definition': '/docs/simulation/concepts/agent-definition',
   '/docs/tracing/concepts/components': '/docs/tracing/concepts',
-  '/docs/tracing/manual/add-attributes-metadata-tags': '/docs/observe/features/manual-tracing/add-attributes-metadata-tags',
-  '/docs/tracing/manual/add-events-exceptions-status': '/docs/observe/features/manual-tracing/add-events-exceptions-status',
-  '/docs/tracing/manual/advanced-tracing-examples': '/docs/observe/features/manual-tracing/advanced-tracing-examples',
-  '/docs/tracing/manual/langfuse-integration': '/docs/observe/features/manual-tracing/langfuse-integration',
-  '/docs/tracing/manual/set-session-user-id': '/docs/observe/features/manual-tracing/set-session-user-id',
-  '/docs/tracing/manual/set-up-tracing': '/docs/observe/features/manual-tracing/set-up-tracing',
+  '/docs/tracing/manual/add-attributes-metadata-tags': '/docs/sdk/tracing/add-attributes-metadata-tags',
+  '/docs/tracing/manual/add-events-exceptions-status': '/docs/sdk/tracing/add-events-exceptions-status',
+  '/docs/tracing/manual/advanced-tracing-examples': '/docs/sdk/tracing/advanced-tracing-examples',
+  '/docs/tracing/manual/langfuse-integration': '/docs/sdk/tracing/langfuse-integration',
+  '/docs/tracing/manual/set-session-user-id': '/docs/sdk/tracing/set-session-user-id',
+  '/docs/tracing/manual/set-up-tracing': '/docs/sdk/tracing/set-up-tracing',
   '/docs/prism': '/docs/command-center',
   '/docs/prism/concepts/api-reference': '/docs/command-center/concepts/api-reference',
   '/docs/prism/concepts/configuration': '/docs/command-center/concepts/configuration',
@@ -77,7 +97,7 @@ export const redirectMap: Record<string, string> = {
   '/cookbook/cookbook5/How-to-build-and-incrementally-improve-RAG-applications-in-Langchain': '/docs/cookbook/rag-langchain',
   '/cookbook/cookbook6/How-to-evaluate-RAG-Applications': '/docs/cookbook/evaluate-rag',
   '/cookbook/cookbook7/Creating-Trustworthy-RAGs-for-Chatbots': '/docs/cookbook/trustworthy-rag',
-  '/cookbook/cookbook8/How-To-Implement-Observability': '/docs/cookbook/observability',
+  '/cookbook/cookbook8/How-To-Implement-Observability': '/docs/cookbook/observe-langgraph-agent-and-obtain-insights',
   '/cookbook/cookbook9/How-To-Decrease-RAG-Hallucination': '/docs/cookbook/decrease-hallucination',
   '/cookbook/integrations/mongodb': '/docs/cookbook/mongodb',
   '/cookbook/optimization/basic-prompt-optimization': '/docs/cookbook/basic-optimization',
@@ -163,20 +183,20 @@ export const redirectMap: Record<string, string> = {
   '/future-agi/get-started/knowledge-base/how-to/create-kb-using-sdk': '/docs/knowledge-base/features/sdk',
   '/future-agi/get-started/knowledge-base/how-to/create-kb-using-ui': '/docs/knowledge-base/features/ui',
   '/future-agi/get-started/knowledge-base/overview': '/docs/knowledge-base',
-  '/future-agi/get-started/observability/manual-tracing/add-attributes-metadata-tags': '/docs/observe/features/manual-tracing/add-attributes-metadata-tags',
-  '/future-agi/get-started/observability/manual-tracing/add-events-exceptions-status': '/docs/observe/features/manual-tracing/add-events-exceptions-status',
-  '/future-agi/get-started/observability/manual-tracing/advanced-tracing-examples': '/docs/observe/features/manual-tracing/advanced-tracing-examples',
-  '/future-agi/get-started/observability/manual-tracing/annotating-using-api': '/docs/observe/features/manual-tracing/annotating-using-api',
-  '/future-agi/get-started/observability/manual-tracing/create-tool-spans': '/docs/observe/features/manual-tracing/create-tool-spans',
-  '/future-agi/get-started/observability/manual-tracing/get-current-span-context': '/docs/observe/features/manual-tracing/get-current-span-context',
-  '/future-agi/get-started/observability/manual-tracing/in-line-evals': '/docs/observe/features/manual-tracing/in-line-evals',
-  '/future-agi/get-started/observability/manual-tracing/instrument-with-traceai-helpers': '/docs/observe/features/manual-tracing/instrument-with-traceai-helpers',
-  '/future-agi/get-started/observability/manual-tracing/langfuse-intergation': '/docs/observe/features/manual-tracing/langfuse-integration',
-  '/future-agi/get-started/observability/manual-tracing/log-prompt-templates': '/docs/observe/features/manual-tracing/log-prompt-templates',
-  '/future-agi/get-started/observability/manual-tracing/mask-span-attributes': '/docs/observe/features/manual-tracing/mask-span-attributes',
-  '/future-agi/get-started/observability/manual-tracing/semantic-conventions': '/docs/observe/features/manual-tracing/semantic-conventions',
-  '/future-agi/get-started/observability/manual-tracing/set-session-user-id': '/docs/observe/features/manual-tracing/set-session-user-id',
-  '/future-agi/get-started/observability/manual-tracing/set-up-tracing': '/docs/observe/features/manual-tracing/set-up-tracing',
+  '/future-agi/get-started/observability/manual-tracing/add-attributes-metadata-tags': '/docs/sdk/tracing/add-attributes-metadata-tags',
+  '/future-agi/get-started/observability/manual-tracing/add-events-exceptions-status': '/docs/sdk/tracing/add-events-exceptions-status',
+  '/future-agi/get-started/observability/manual-tracing/advanced-tracing-examples': '/docs/sdk/tracing/advanced-tracing-examples',
+  '/future-agi/get-started/observability/manual-tracing/annotating-using-api': '/docs/sdk/tracing/annotating-using-api',
+  '/future-agi/get-started/observability/manual-tracing/create-tool-spans': '/docs/sdk/tracing/create-tool-spans',
+  '/future-agi/get-started/observability/manual-tracing/get-current-span-context': '/docs/sdk/tracing/get-current-span-context',
+  '/future-agi/get-started/observability/manual-tracing/in-line-evals': '/docs/sdk/tracing/in-line-evals',
+  '/future-agi/get-started/observability/manual-tracing/instrument-with-traceai-helpers': '/docs/sdk/tracing/instrument-with-traceai-helpers',
+  '/future-agi/get-started/observability/manual-tracing/langfuse-intergation': '/docs/sdk/tracing/langfuse-integration',
+  '/future-agi/get-started/observability/manual-tracing/log-prompt-templates': '/docs/sdk/tracing/log-prompt-templates',
+  '/future-agi/get-started/observability/manual-tracing/mask-span-attributes': '/docs/sdk/tracing/mask-span-attributes',
+  '/future-agi/get-started/observability/manual-tracing/semantic-conventions': '/docs/sdk/tracing/semantic-conventions',
+  '/future-agi/get-started/observability/manual-tracing/set-session-user-id': '/docs/sdk/tracing/set-session-user-id',
+  '/future-agi/get-started/observability/manual-tracing/set-up-tracing': '/docs/sdk/tracing/set-up-tracing',
   '/future-agi/get-started/optimization/dataset-optimization': '/docs/cookbook/quickstart/dataset-optimization',
   '/future-agi/get-started/optimization/how-to/using-python-sdk': '/docs/optimization/features/using-python-sdk',
   '/future-agi/get-started/optimization/optimizers/bayesian-search': '/docs/optimization/optimizers/bayesian-search',

src/pages/docs/cookbook/index.mdx

@@ -111,11 +111,11 @@ description: "Practical step-by-step guides for evaluation, optimization, simula
 
 <CardGroup cols={3}>
   <Card
-    title="LangChain Chatbot"
-    href="/docs/cookbook/observability"
+    title="Observing a LangGraph agent and obtaining insights"
+    href="/docs/cookbook/observe-langgraph-agent-and-obtain-insights"
     img="/images/agi2.png"
   >
-    Add monitoring and observability to your AI applications
+    Trace a support agent by session and user, score it with an Eval Task, and read the scores as insights
   </Card>
   <Card
     title="Text-to-SQL Agent"