@sanity/ailf-studio 1.15.0 → 1.16.0

package/dist/index.d.ts

@@ -622,6 +622,13 @@ interface RecommendationsData {
  */
 interface StoredTestResultData {
     area: string;
+    /**
+     * Documentation context the task expected the model to use.
+     * Legacy alias `canonicalDocs` may appear on pre-Phase-2 reports;
+     * Studio reader components fall back via `??`.
+     */
+    contextDocs?: DocumentRef[];
+    /** @deprecated legacy alias for contextDocs on pre-Phase-2 reports */
     canonicalDocs?: DocumentRef[];
     compositeScore?: number;
     cost?: number;
@@ -646,7 +653,13 @@ interface StoredTestResultData {
 }
 /** A single low-scoring grader judgment stored in reports */
 interface JudgmentData {
-    /** Docs the task expected the model to use */
+    /**
+     * Documentation context the task expected the model to use.
+     * Legacy alias `canonicalDocs` may appear on pre-Phase-2 reports;
+     * Studio reader components fall back via `??`.
+     */
+    contextDocs?: DocumentRef[];
+    /** @deprecated legacy alias for contextDocs on pre-Phase-2 reports */
     canonicalDocs?: DocumentRef[];
     dimension: string;
     /**
@@ -926,9 +939,9 @@ declare const GLOSSARY: {
     readonly strengths: "What's working well: high-scoring areas, dimensions where the docs are strong, and areas where AI agents successfully find and use the documentation.";
     readonly recommendations: "Prioritized remediation plan from gap analysis. Each recommendation identifies a documentation problem, the affected feature area, and the estimated score lift from fixing it.";
     readonly totalPotentialLift: "Aggregate potential score lift if all identified gaps were fixed. This is a conservative estimate — each gap targets the median of non-bottlenecked dimensions, not 100.";
-    readonly failureMode: "The type of documentation problem: missing-docs (functionality not covered), incorrect-docs (factual errors), outdated-docs (stale API/patterns), or poor-structure (hard to find/understand).";
+    readonly failureMode: "The type of failure the grader emitted. Cross-cutting modes apply to any dimension (api-error, model-limitation, false-floor, unclassified). Per-dimension extensions cover documentation problems (missing-docs, incorrect-docs, outdated-docs, poor-structure), spec adherence (spec-mismatch), tool use (tool-misuse, chaotic-process, missing-recovery), and knowledge probes (factual-error, incompleteness, currency-violation, hallucination).";
     readonly estimatedLift: "Estimated composite score improvement if this gap is fully fixed. Based on raising bottleneck dimensions to the median of non-bottlenecked dimensions.";
-    readonly confidence: "How confident the classifier is in this diagnosis. High = strong keyword + structural signal agreement. Medium = partial agreement. Low = weak signals only.";
+    readonly confidence: "How confident we are in this diagnosis (D0049 ceiling-cross-check derivation). High = the grader's emitted failure mode agrees with the structural ceiling-decomposition signal. Medium = signals disagree (or the ceiling pattern is not informative for this score). Low = passing scores never classify; treat as absent.";
     readonly agentBehaviorOverview: "How AI agents interacted with your documentation during evaluation: what they searched for, which pages they visited, and how much time they spent on network requests.";
     readonly searchQueries: "The exact search queries agents used to find documentation. Helps you understand how agents discover your content and whether your docs appear for relevant queries.";
     readonly docSlugsVisited: "Documentation page slugs that agents actually visited during evaluation. Compare against canonical docs to see if agents found the right pages.";

package/dist/index.js

@@ -1525,16 +1525,8 @@ var reportSchema = defineType4({
                     }),
                     defineField4({
                       name: "failureMode",
-                      options: {
-                        list: [
-                          "missing-docs",
-                          "incorrect-docs",
-                          "outdated-docs",
-                          "poor-structure",
-                          "model-limitation",
-                          "unclassified"
-                        ]
-                      },
+                      description: "Per-dimension failure-mode tag \u2014 taxonomy lives in @sanity/ailf packages/eval/src/grader/ and is enumerated by the runtime grader prompt. The Studio dropdown is intentionally unconstrained so taxonomy edits don't require Studio schema PRs (Plan 03-02).",
+                      readOnly: true,
                       title: "Failure Mode",
                       type: "string"
                     }),
@@ -1600,14 +1592,8 @@ var reportSchema = defineType4({
                   type: "string"
                 }),
                 defineField4({
+                  description: "Free-form dimension slug \u2014 per-dimension taxonomies (Plan 03-02) ship kebab-case values beyond the closed literacy triple (e.g. factual-correctness, assertion-pass-rate, input-validation).",
                   name: "dimension",
-                  options: {
-                    list: [
-                      "task-completion",
-                      "code-correctness",
-                      "doc-coverage"
-                    ]
-                  },
                   title: "Dimension",
                   type: "string"
                 }),
@@ -2326,8 +2312,17 @@ import {
 } from "sanity";
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 function CanonicalDocPreview(props) {
-  const { perspective, perspectiveTitle, reason, refType, slug, path } = props;
+  const {
+    docType,
+    perspective,
+    perspectiveTitle,
+    reason,
+    refType,
+    slug,
+    path
+  } = props;
   const isPerspective = refType === "perspective";
+  const isNonArticleDoc = !isPerspective && typeof docType === "string" && docType !== "article";
   const { data: activeReleases } = useActiveReleases();
   const { data: archivedReleases } = useArchivedReleases();
   const resolvedTitle = useMemo(() => {
@@ -2374,7 +2369,14 @@ function CanonicalDocPreview(props) {
   return /* @__PURE__ */ jsxs5(Flex3, { align: "center", gap: 2, padding: 2, children: [
     /* @__PURE__ */ jsx5(Text5, { size: 2, children: icon }),
     /* @__PURE__ */ jsxs5(Flex3, { direction: "column", gap: 1, flex: 1, children: [
-      /* @__PURE__ */ jsx5(Text5, { size: 2, weight: "semibold", children: resolvedTitle }),
+      /* @__PURE__ */ jsxs5(Flex3, { align: "center", gap: 2, children: [
+        /* @__PURE__ */ jsx5(Text5, { size: 2, weight: "semibold", children: resolvedTitle }),
+        isNonArticleDoc && /* @__PURE__ */ jsxs5(Text5, { muted: true, size: 0, children: [
+          "(",
+          docType,
+          ")"
+        ] })
+      ] }),
       subtitle && /* @__PURE__ */ jsx5(Text5, { muted: true, size: 1, children: subtitle })
     ] })
   ] });
@@ -2839,6 +2841,17 @@ var taskSchema = defineType5({
                     select: { subtitle: "slug.current", title: "title" }
                   },
                   type: "article"
+                },
+                // typesReference — SDK / API type-definition documents.
+                // The pipeline resolves these via the renderer registry
+                // (see packages/eval/src/sanity/document-renderers.ts);
+                // adding more curated types here is a one-line schema
+                // change with no other code path required (W0195).
+                {
+                  preview: {
+                    select: { subtitle: "slug.current", title: "title" }
+                  },
+                  type: "typesReference"
                 }
               ],
               type: "crossDatasetReference",
@@ -2897,6 +2910,7 @@ var taskSchema = defineType5({
           name: "canonicalDocRef",
           preview: {
             select: {
+              docType: "doc._type",
               path: "path",
               perspective: "perspective",
               perspectiveTitle: "perspectiveTitle",
@@ -2961,10 +2975,37 @@ var taskSchema = defineType5({
               type: "string"
             }),
             defineField5({
-              description: "Task-specific criteria bullets (only for llm-rubric type). Each item describes a specific aspect the grader should check.",
+              description: "Task-specific criteria bullets (only for llm-rubric type). Each criterion has a stable id + text. The id auto-derives from text on first save.",
               hidden: ({ parent }) => parent?.type !== "llm-rubric",
               name: "criteria",
-              of: [{ type: "string" }],
+              of: [
+                {
+                  name: "criterion",
+                  type: "object",
+                  fields: [
+                    defineField5({
+                      name: "id",
+                      title: "Criterion ID",
+                      type: "slug",
+                      options: { source: "text", maxLength: 60 },
+                      validation: (rule) => rule.required().custom((value) => {
+                        if (!value?.current) return "ID is required";
+                        return /^[a-z0-9][a-z0-9-]*$/.test(value.current) || "Must be lowercase alphanumeric with hyphens";
+                      })
+                    }),
+                    defineField5({
+                      name: "text",
+                      title: "Criterion Text",
+                      type: "text",
+                      rows: 2,
+                      validation: (rule) => rule.required()
+                    })
+                  ],
+                  preview: {
+                    select: { title: "text", subtitle: "id.current" }
+                  }
+                }
+              ],
               title: "Criteria",
               type: "array"
             }),
@@ -3871,7 +3912,7 @@ Click into any report for the full breakdown: per-area scores, diagnostics, and
   {
     "id": "glossary",
     "title": "Glossary",
-    "body": "**Overall Score**\n: A weighted average across all feature areas, using the gold scoring profile: Task Completion (50%), Code Correctness (25%), and Doc Coverage (25%).\n\n**Doc Lift**\n: How much the docs help, compared to the model's training data alone. Calculated as ceiling minus floor, where ceiling includes Doc Coverage and floor does not. Higher is better.\n\n**Actual Score**\n: How well an AI agent scores when it has to find docs on its own through web search and page fetching. This is the real-world scenario. Only available in full mode.\n\n**Retrieval Gap**\n: The score lost because agents can't find or use all the relevant docs. Calculated as ceiling minus actual. Lower is better; zero means agents find everything.\n\n**Infra Efficiency**\n: What percentage of the docs' potential quality actually reaches agents (actual \xF7 ceiling). 100% means agents find and use all relevant docs perfectly.\n\n**Floor**\n: Output-quality composite without documentation \u2014 Task Completion (60%) and Code Correctness (40%) only. Doc Coverage is excluded because it's undefined when no docs are provided. This tells you what the model already knows from its training data.\n\n**Ceiling**\n: Score with gold-standard docs injected directly into the prompt. This is the best the documentation can do.\n\n**Actual**\n: Score when an AI agent finds docs on its own through web search and page fetching. This is the real-world experience.\n\n**Ret Gap**\n: Quality lost to discoverability (ceiling minus actual). The gap between what the docs could deliver and what agents actually get.\n\n**Efficiency**\n: What fraction of the docs' quality reaches agents in practice (actual \xF7 ceiling, shown as a percentage).\n\n**Inverted Ret Gap**\n: \u26A0\uFE0F Inverted retrieval gap: agents that can't find the docs actually score higher, because the docs hurt performance. This usually means there's a doc quality problem.\n\n**Score**\n: Ceiling composite for this feature area: Task Completion \xD7 50% + Code Correctness \xD7 25% + Doc Coverage \xD7 25%.\n\n**Task Completion**\n: Can the LLM implement the requested feature? Graded 0\u2013100.\n\n**Code Correctness**\n: Is the generated code idiomatic, correct, and following best practices? Graded 0\u2013100.\n\n**Doc Coverage**\n: Did the docs provide the information needed to implement the feature? Graded 0\u2013100. This dimension only contributes to the ceiling composite (with docs) \u2014 it's excluded from the floor composite because it's undefined without documentation.\n\n**Tests**\n: Number of test cases in this feature area.\n\n**Overall Delta**\n: Change in overall score between the two runs. Positive means the experiment scored higher.\n\n**Actual Delta**\n: Change in actual (agent-retrieved) score between runs. Positive means agents did better.\n\n**Ret Gap Delta**\n: Change in retrieval gap between runs. Negative is good here: it means the gap shrank and agents found more relevant docs.\n\n**Efficiency Delta**\n: Change in infrastructure efficiency between runs. Positive means agents are capturing more of the docs' potential.\n\n**Baseline**\n: The reference run you're comparing against.\n\n**Experiment**\n: The new run you're evaluating.\n\n**Delta**\n: Difference between experiment and baseline. Positive means improvement, negative means regression.\n\n**Change**\n: Whether the change is meaningful: improved, regressed, or unchanged (within the noise threshold).\n\n**Low Scoring Judgments**\n: The grading model's explanations for tests that scored below 70/100.\n\n**Judgment Reason**\n: The grading model's natural language explanation of what went wrong.\n\n**Health Strong**\n: Feature areas scoring 80 or above. The docs are working well for these features \u2014 AI agents produce correct, complete implementations.\n\n**Health Attention**\n: Feature areas scoring 70\u201379. These are okay but could be improved \u2014 there may be gaps in specific dimensions like doc coverage or code correctness.\n\n**Health Weak**\n: Feature areas scoring below 70. The docs are not providing enough support for AI agents to implement these features correctly.\n\n**Negative Doc Lift Metric**\n: Number of areas where the documentation actually hurts AI performance \u2014 the model scores higher without docs than with them. This usually means the docs contain outdated patterns or incorrect examples.\n\n**Weak Areas**\n: Feature areas where the overall score is below 70. These need the most attention \u2014 low scores mean AI agents consistently struggle to implement these features.\n\n**Docs Hurt**\n: Areas where the floor score (no docs) is higher than the ceiling score (with docs). The documentation may be actively misleading the model. These docs should be reviewed.\n\n**Retrieval Issues**\n: Areas where AI agents can find less than 70% of the available doc quality. The docs exist and are good, but agents can't discover them through search. Consider improving page titles, metadata, or search engine indexing.\n\n**Dim Weaknesses**\n: Individual grading dimensions scoring below 50 within an area. These are the specific skills where AI agents fail most \u2014 task completion (can it build the feature?), code correctness (is the code right?), or doc coverage (did it use the docs?).\n\n**Efficiency Anomalies**\n: Areas where agent efficiency exceeds 100% \u2014 meaning agents perform better with self-found docs than with gold-standard docs injected directly. This can indicate doc quality issues (injected docs confuse the model) or agent memorization.\n\n**Doc Lift Wins**\n: Areas where documentation boosts AI performance by 5 or more points. Higher doc lift means the docs are providing crucial information that the model doesn't already know.\n\n**Retrieval Excellence**\n: Areas where AI agents successfully find and use at least 85% of the available doc quality through web search. Good retrieval means your docs are well-indexed and easy for agents to discover.\n\n**Model Breakdown**\n: Break down scores by individual LLM model. The default 'All Models' view shows the cross-model average. Select a specific model to see how it performed independently \u2014 useful for spotting models that struggle with specific feature areas.\n\n**Strengths**\n: What's working well: high-scoring areas, dimensions where the docs are strong, and areas where AI agents successfully find and use the documentation.\n\n**Recommendations**\n: Prioritized remediation plan from gap analysis. Each recommendation identifies a documentation problem, the affected feature area, and the estimated score lift from fixing it.\n\n**Total Potential Lift**\n: Aggregate potential score lift if all identified gaps were fixed. This is a conservative estimate \u2014 each gap targets the median of non-bottlenecked dimensions, not 100.\n\n**Failure Mode**\n: The type of documentation problem: missing-docs (functionality not covered), incorrect-docs (factual errors), outdated-docs (stale API/patterns), or poor-structure (hard to find/understand).\n\n**Estimated Lift**\n: Estimated composite score improvement if this gap is fully fixed. Based on raising bottleneck dimensions to the median of non-bottlenecked dimensions.\n\n**Confidence**\n: How confident the classifier is in this diagnosis. High = strong keyword + structural signal agreement. Medium = partial agreement. Low = weak signals only.\n\n**Agent Behavior Overview**\n: How AI agents interacted with your documentation during evaluation: what they searched for, which pages they visited, and how much time they spent on network requests.\n\n**Search Queries**\n: The exact search queries agents used to find documentation. Helps you understand how agents discover your content and whether your docs appear for relevant queries.\n\n**Doc Slugs Visited**\n: Documentation page slugs that agents actually visited during evaluation. Compare against canonical docs to see if agents found the right pages.\n\n**External Domains**\n: Non-Sanity domains that agents contacted during evaluation. High external domain counts may indicate agents couldn't find what they needed in your docs.\n\n**Avg Doc Pages Visited**\n: Average number of documentation pages visited per test. Higher counts can mean agents need to consult many pages (complex task) or can't find the right one quickly.\n\n**Avg Searches Performed**\n: Average number of web searches performed per test. High search counts can indicate docs are hard to discover through search engines.\n\n**Avg Network Time Ms**\n: Average time spent on network requests per test. Includes page fetches, search queries, and API calls.\n\n**Total Requests**\n: Total number of HTTP requests the agent made during the test, including searches, page visits, and API calls.\n\n**Total Bytes Downloaded**\n: Total bytes downloaded by the agent. Large downloads may indicate the agent is fetching many pages or very large documents.\n\n**Dim Task Completion**\n: Change in task completion between runs. Positive means implementations are more complete.\n\n**Dim Code Correctness**\n: Change in code correctness between runs. Positive means better code quality.\n\n**Dim Doc Coverage**\n: Change in doc coverage between runs. Positive means the docs are providing more useful information.\n\n**Area Delta**\n: Score change for this area compared to the previous evaluation run.\n\n**Source Production**\n: Production source \u2014 docs fetched from the live production dataset. Scores reflect what real users and AI agents experience today.\n\n**Source Branch**\n: Branch source \u2014 docs fetched from a branch or draft dataset. Use this to preview how content changes affect scores before publishing.\n\n**Source Local**\n: Local source \u2014 docs fetched from local files or a local dev server. Useful for testing doc changes before pushing.\n\n**Report Score**\n: The overall ceiling composite for this evaluation run: Task Completion (50%), Code Correctness (25%), and Doc Coverage (25%), averaged across all feature areas.\n\n**Report Mode**\n: The evaluation mode determines which reference points are measured. Different modes test different aspects of how AI agents interact with documentation.\n\n**Report Trigger**\n: What initiated this evaluation run. Knowing the trigger helps you understand whether a score change was from a content edit, a code deploy, or a scheduled check.\n\n**Mode Baseline**\n: Baseline mode \u2014 tests the model with gold-standard docs injected directly. Measures ceiling performance (best the docs can do).\n\n**Mode Full**\n: Full mode \u2014 runs baseline + agentic. Compares ceiling (injected docs) against actual (agent-retrieved docs) to measure retrieval gap and infrastructure efficiency.\n\n**Mode Agentic**\n: Agentic mode \u2014 the AI agent finds docs on its own via web search. Measures real-world performance: can agents actually discover and use your documentation?\n\n**Mode Observed**\n: Observed mode \u2014 records how agents interact with docs without scoring. Captures search queries, pages visited, and browsing patterns for analysis.\n\n**Mode Debug**\n: Debug mode \u2014 a diagnostic run for pipeline development. May use non-standard configurations or limited task sets.\n\n**Trigger Manual**\n: Manually triggered \u2014 someone ran the evaluation pipeline by hand, either locally or via the Studio UI.\n\n**Trigger Ci**\n: CI-triggered \u2014 the evaluation ran automatically as part of a pull request or merge pipeline.\n\n**Trigger Schedule**\n: Scheduled \u2014 the evaluation ran on a recurring schedule (e.g. nightly or weekly) to track score trends over time.\n\n**Trigger Webhook**\n: Webhook-triggered \u2014 a content change in Sanity triggered the evaluation automatically. Helps catch doc regressions early.\n\n**Trigger Cross Repo**\n: Cross-repo \u2014 triggered from another repository via the dispatch API. Used when external repos want to validate their docs against AILF tasks.",
+    "body": "**Overall Score**\n: A weighted average across all feature areas, using the gold scoring profile: Task Completion (50%), Code Correctness (25%), and Doc Coverage (25%).\n\n**Doc Lift**\n: How much the docs help, compared to the model's training data alone. Calculated as ceiling minus floor, where ceiling includes Doc Coverage and floor does not. Higher is better.\n\n**Actual Score**\n: How well an AI agent scores when it has to find docs on its own through web search and page fetching. This is the real-world scenario. Only available in full mode.\n\n**Retrieval Gap**\n: The score lost because agents can't find or use all the relevant docs. Calculated as ceiling minus actual. Lower is better; zero means agents find everything.\n\n**Infra Efficiency**\n: What percentage of the docs' potential quality actually reaches agents (actual \xF7 ceiling). 100% means agents find and use all relevant docs perfectly.\n\n**Floor**\n: Output-quality composite without documentation \u2014 Task Completion (60%) and Code Correctness (40%) only. Doc Coverage is excluded because it's undefined when no docs are provided. This tells you what the model already knows from its training data.\n\n**Ceiling**\n: Score with gold-standard docs injected directly into the prompt. This is the best the documentation can do.\n\n**Actual**\n: Score when an AI agent finds docs on its own through web search and page fetching. This is the real-world experience.\n\n**Ret Gap**\n: Quality lost to discoverability (ceiling minus actual). The gap between what the docs could deliver and what agents actually get.\n\n**Efficiency**\n: What fraction of the docs' quality reaches agents in practice (actual \xF7 ceiling, shown as a percentage).\n\n**Inverted Ret Gap**\n: \u26A0\uFE0F Inverted retrieval gap: agents that can't find the docs actually score higher, because the docs hurt performance. This usually means there's a doc quality problem.\n\n**Score**\n: Ceiling composite for this feature area: Task Completion \xD7 50% + Code Correctness \xD7 25% + Doc Coverage \xD7 25%.\n\n**Task Completion**\n: Can the LLM implement the requested feature? Graded 0\u2013100.\n\n**Code Correctness**\n: Is the generated code idiomatic, correct, and following best practices? Graded 0\u2013100.\n\n**Doc Coverage**\n: Did the docs provide the information needed to implement the feature? Graded 0\u2013100. This dimension only contributes to the ceiling composite (with docs) \u2014 it's excluded from the floor composite because it's undefined without documentation.\n\n**Tests**\n: Number of test cases in this feature area.\n\n**Overall Delta**\n: Change in overall score between the two runs. Positive means the experiment scored higher.\n\n**Actual Delta**\n: Change in actual (agent-retrieved) score between runs. Positive means agents did better.\n\n**Ret Gap Delta**\n: Change in retrieval gap between runs. Negative is good here: it means the gap shrank and agents found more relevant docs.\n\n**Efficiency Delta**\n: Change in infrastructure efficiency between runs. Positive means agents are capturing more of the docs' potential.\n\n**Baseline**\n: The reference run you're comparing against.\n\n**Experiment**\n: The new run you're evaluating.\n\n**Delta**\n: Difference between experiment and baseline. Positive means improvement, negative means regression.\n\n**Change**\n: Whether the change is meaningful: improved, regressed, or unchanged (within the noise threshold).\n\n**Low Scoring Judgments**\n: The grading model's explanations for tests that scored below 70/100.\n\n**Judgment Reason**\n: The grading model's natural language explanation of what went wrong.\n\n**Health Strong**\n: Feature areas scoring 80 or above. The docs are working well for these features \u2014 AI agents produce correct, complete implementations.\n\n**Health Attention**\n: Feature areas scoring 70\u201379. These are okay but could be improved \u2014 there may be gaps in specific dimensions like doc coverage or code correctness.\n\n**Health Weak**\n: Feature areas scoring below 70. The docs are not providing enough support for AI agents to implement these features correctly.\n\n**Negative Doc Lift Metric**\n: Number of areas where the documentation actually hurts AI performance \u2014 the model scores higher without docs than with them. This usually means the docs contain outdated patterns or incorrect examples.\n\n**Weak Areas**\n: Feature areas where the overall score is below 70. These need the most attention \u2014 low scores mean AI agents consistently struggle to implement these features.\n\n**Docs Hurt**\n: Areas where the floor score (no docs) is higher than the ceiling score (with docs). The documentation may be actively misleading the model. These docs should be reviewed.\n\n**Retrieval Issues**\n: Areas where AI agents can find less than 70% of the available doc quality. The docs exist and are good, but agents can't discover them through search. Consider improving page titles, metadata, or search engine indexing.\n\n**Dim Weaknesses**\n: Individual grading dimensions scoring below 50 within an area. These are the specific skills where AI agents fail most \u2014 task completion (can it build the feature?), code correctness (is the code right?), or doc coverage (did it use the docs?).\n\n**Efficiency Anomalies**\n: Areas where agent efficiency exceeds 100% \u2014 meaning agents perform better with self-found docs than with gold-standard docs injected directly. This can indicate doc quality issues (injected docs confuse the model) or agent memorization.\n\n**Doc Lift Wins**\n: Areas where documentation boosts AI performance by 5 or more points. Higher doc lift means the docs are providing crucial information that the model doesn't already know.\n\n**Retrieval Excellence**\n: Areas where AI agents successfully find and use at least 85% of the available doc quality through web search. Good retrieval means your docs are well-indexed and easy for agents to discover.\n\n**Model Breakdown**\n: Break down scores by individual LLM model. The default 'All Models' view shows the cross-model average. Select a specific model to see how it performed independently \u2014 useful for spotting models that struggle with specific feature areas.\n\n**Strengths**\n: What's working well: high-scoring areas, dimensions where the docs are strong, and areas where AI agents successfully find and use the documentation.\n\n**Recommendations**\n: Prioritized remediation plan from gap analysis. Each recommendation identifies a documentation problem, the affected feature area, and the estimated score lift from fixing it.\n\n**Total Potential Lift**\n: Aggregate potential score lift if all identified gaps were fixed. This is a conservative estimate \u2014 each gap targets the median of non-bottlenecked dimensions, not 100.\n\n**Failure Mode**\n: The type of failure the grader emitted. Cross-cutting modes apply to any dimension (api-error, model-limitation, false-floor, unclassified). Per-dimension extensions cover documentation problems (missing-docs, incorrect-docs, outdated-docs, poor-structure), spec adherence (spec-mismatch), tool use (tool-misuse, chaotic-process, missing-recovery), and knowledge probes (factual-error, incompleteness, currency-violation, hallucination).\n\n**Estimated Lift**\n: Estimated composite score improvement if this gap is fully fixed. Based on raising bottleneck dimensions to the median of non-bottlenecked dimensions.\n\n**Confidence**\n: How confident we are in this diagnosis (D0049 ceiling-cross-check derivation). High = the grader's emitted failure mode agrees with the structural ceiling-decomposition signal. Medium = signals disagree (or the ceiling pattern is not informative for this score). Low = passing scores never classify; treat as absent.\n\n**Agent Behavior Overview**\n: How AI agents interacted with your documentation during evaluation: what they searched for, which pages they visited, and how much time they spent on network requests.\n\n**Search Queries**\n: The exact search queries agents used to find documentation. Helps you understand how agents discover your content and whether your docs appear for relevant queries.\n\n**Doc Slugs Visited**\n: Documentation page slugs that agents actually visited during evaluation. Compare against canonical docs to see if agents found the right pages.\n\n**External Domains**\n: Non-Sanity domains that agents contacted during evaluation. High external domain counts may indicate agents couldn't find what they needed in your docs.\n\n**Avg Doc Pages Visited**\n: Average number of documentation pages visited per test. Higher counts can mean agents need to consult many pages (complex task) or can't find the right one quickly.\n\n**Avg Searches Performed**\n: Average number of web searches performed per test. High search counts can indicate docs are hard to discover through search engines.\n\n**Avg Network Time Ms**\n: Average time spent on network requests per test. Includes page fetches, search queries, and API calls.\n\n**Total Requests**\n: Total number of HTTP requests the agent made during the test, including searches, page visits, and API calls.\n\n**Total Bytes Downloaded**\n: Total bytes downloaded by the agent. Large downloads may indicate the agent is fetching many pages or very large documents.\n\n**Dim Task Completion**\n: Change in task completion between runs. Positive means implementations are more complete.\n\n**Dim Code Correctness**\n: Change in code correctness between runs. Positive means better code quality.\n\n**Dim Doc Coverage**\n: Change in doc coverage between runs. Positive means the docs are providing more useful information.\n\n**Area Delta**\n: Score change for this area compared to the previous evaluation run.\n\n**Source Production**\n: Production source \u2014 docs fetched from the live production dataset. Scores reflect what real users and AI agents experience today.\n\n**Source Branch**\n: Branch source \u2014 docs fetched from a branch or draft dataset. Use this to preview how content changes affect scores before publishing.\n\n**Source Local**\n: Local source \u2014 docs fetched from local files or a local dev server. Useful for testing doc changes before pushing.\n\n**Report Score**\n: The overall ceiling composite for this evaluation run: Task Completion (50%), Code Correctness (25%), and Doc Coverage (25%), averaged across all feature areas.\n\n**Report Mode**\n: The evaluation mode determines which reference points are measured. Different modes test different aspects of how AI agents interact with documentation.\n\n**Report Trigger**\n: What initiated this evaluation run. Knowing the trigger helps you understand whether a score change was from a content edit, a code deploy, or a scheduled check.\n\n**Mode Baseline**\n: Baseline mode \u2014 tests the model with gold-standard docs injected directly. Measures ceiling performance (best the docs can do).\n\n**Mode Full**\n: Full mode \u2014 runs baseline + agentic. Compares ceiling (injected docs) against actual (agent-retrieved docs) to measure retrieval gap and infrastructure efficiency.\n\n**Mode Agentic**\n: Agentic mode \u2014 the AI agent finds docs on its own via web search. Measures real-world performance: can agents actually discover and use your documentation?\n\n**Mode Observed**\n: Observed mode \u2014 records how agents interact with docs without scoring. Captures search queries, pages visited, and browsing patterns for analysis.\n\n**Mode Debug**\n: Debug mode \u2014 a diagnostic run for pipeline development. May use non-standard configurations or limited task sets.\n\n**Trigger Manual**\n: Manually triggered \u2014 someone ran the evaluation pipeline by hand, either locally or via the Studio UI.\n\n**Trigger Ci**\n: CI-triggered \u2014 the evaluation ran automatically as part of a pull request or merge pipeline.\n\n**Trigger Schedule**\n: Scheduled \u2014 the evaluation ran on a recurring schedule (e.g. nightly or weekly) to track score trends over time.\n\n**Trigger Webhook**\n: Webhook-triggered \u2014 a content change in Sanity triggered the evaluation automatically. Helps catch doc regressions early.\n\n**Trigger Cross Repo**\n: Cross-repo \u2014 triggered from another repository via the dispatch API. Used when external repos want to validate their docs against AILF tasks.",
     "source": "packages/studio/src/glossary.ts",
     "tags": [
       "reference",
@@ -3970,9 +4011,9 @@ var GLOSSARY = {
   // -- Recommendations / gap analysis ----------------------------------------
   recommendations: "Prioritized remediation plan from gap analysis. Each recommendation identifies a documentation problem, the affected feature area, and the estimated score lift from fixing it.",
   totalPotentialLift: "Aggregate potential score lift if all identified gaps were fixed. This is a conservative estimate \u2014 each gap targets the median of non-bottlenecked dimensions, not 100.",
-  failureMode: "The type of documentation problem: missing-docs (functionality not covered), incorrect-docs (factual errors), outdated-docs (stale API/patterns), or poor-structure (hard to find/understand).",
+  failureMode: "The type of failure the grader emitted. Cross-cutting modes apply to any dimension (api-error, model-limitation, false-floor, unclassified). Per-dimension extensions cover documentation problems (missing-docs, incorrect-docs, outdated-docs, poor-structure), spec adherence (spec-mismatch), tool use (tool-misuse, chaotic-process, missing-recovery), and knowledge probes (factual-error, incompleteness, currency-violation, hallucination).",
   estimatedLift: "Estimated composite score improvement if this gap is fully fixed. Based on raising bottleneck dimensions to the median of non-bottlenecked dimensions.",
-  confidence: "How confident the classifier is in this diagnosis. High = strong keyword + structural signal agreement. Medium = partial agreement. Low = weak signals only.",
+  confidence: "How confident we are in this diagnosis (D0049 ceiling-cross-check derivation). High = the grader's emitted failure mode agrees with the structural ceiling-decomposition signal. Medium = signals disagree (or the ceiling pattern is not informative for this score). Low = passing scores never classify; treat as absent.",
   // -- Agent behavior --------------------------------------------------------
   agentBehaviorOverview: "How AI agents interacted with your documentation during evaluation: what they searched for, which pages they visited, and how much time they spent on network requests.",
   searchQueries: "The exact search queries agents used to find documentation. Helps you understand how agents discover your content and whether your docs appear for relevant queries.",
@@ -4088,6 +4129,20 @@ function getDimensionValue(score, key) {
 }
 
 // src/lib/comparison.ts
+function normalizePerArea(perArea) {
+  if (perArea == null) return [];
+  if (Array.isArray(perArea)) {
+    return perArea.filter(
+      (e) => typeof e === "object" && e !== null && typeof e.area === "string" && typeof e.delta === "number"
+    );
+  }
+  if (typeof perArea === "object") {
+    return Object.entries(perArea).filter(
+      (entry) => typeof entry[1] === "number"
+    ).map(([area, delta]) => ({ area, delta }));
+  }
+  return [];
+}
 function scoreMap(summary) {
   return new Map(summary.scores.map((s) => [s.feature, s]));
 }
@@ -9431,7 +9486,8 @@ function matchesQuery(j, query) {
   if (j.taskId.toLowerCase().includes(q)) return true;
   if (j.reason.toLowerCase().includes(q)) return true;
   if (j.modelId.toLowerCase().includes(q)) return true;
-  return j.canonicalDocs?.some(
+  const docs = j.contextDocs ?? j.canonicalDocs;
+  return docs?.some(
     (d) => (d.title ?? d.slug).toLowerCase().includes(q) || d.slug.toLowerCase().includes(q)
   ) ?? false;
 }
@@ -12058,7 +12114,7 @@ function StrengthsList({
         AreaScoresGrid,
         {
           mode,
-          perArea: comparison?.deltas?.perArea,
+          perArea: normalizePerArea(comparison?.deltas?.perArea),
           perModel: expandedPerModel,
           scores: displayedScores
         }
@@ -12145,7 +12201,7 @@ function WeaknessesList({
   );
   const dimWeaknesses = scores.map((s) => ({ area: s, dims: getDimensionWeaknesses(s) })).filter(({ dims }) => dims.length > 0);
   const regressed = comparison?.regressed ?? [];
-  const perArea = comparison?.deltas?.perArea;
+  const perArea = normalizePerArea(comparison?.deltas?.perArea);
   const efficiencyAnomalies = scores.filter(
     (s) => s.infrastructureEfficiency != null && s.infrastructureEfficiency > EFFICIENCY_ANOMALY
   );
@@ -12358,7 +12414,7 @@ function WeaknessesList({
       ),
       /* @__PURE__ */ jsx56(Stack31, { children: regressed.map((featureName, i) => {
         const area = scores.find((s) => s.feature === featureName);
-        const areaDelta = perArea?.find(
+        const areaDelta = perArea.find(
           (p) => p.area === featureName
         )?.delta;
         return /* @__PURE__ */ jsxs40(
@@ -13300,10 +13356,13 @@ function JudgmentDetailDrawer({
             }
           )
         ] }),
-        judgment.canonicalDocs && judgment.canonicalDocs.length > 0 && /* @__PURE__ */ jsx65(Box33, { padding: 4, style: RELATED_DOCS_STYLE, children: /* @__PURE__ */ jsxs48(Flex35, { align: "center", gap: 2, wrap: "wrap", children: [
-          /* @__PURE__ */ jsx65("span", { style: SECTION_LABEL_STYLE, children: "Related docs" }),
-          judgment.canonicalDocs.map((doc) => /* @__PURE__ */ jsx65(DocBadge, { doc }, doc.slug))
-        ] }) })
+        (() => {
+          const docs = judgment.contextDocs ?? judgment.canonicalDocs;
+          return docs && docs.length > 0 ? /* @__PURE__ */ jsx65(Box33, { padding: 4, style: RELATED_DOCS_STYLE, children: /* @__PURE__ */ jsxs48(Flex35, { align: "center", gap: 2, wrap: "wrap", children: [
+            /* @__PURE__ */ jsx65("span", { style: SECTION_LABEL_STYLE, children: "Related docs" }),
+            docs.map((doc) => /* @__PURE__ */ jsx65(DocBadge, { doc }, doc.slug))
+          ] }) }) : null;
+        })()
       ]
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ailf-studio",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "AI Literacy Framework — Sanity Studio dashboard plugin",
   "type": "module",
   "license": "MIT",
@@ -71,8 +71,7 @@
     "prebuild": "pnpm extract-help",
     "build": "tsup",
     "dev": "tsup --watch",
-    "test": "tsx --test src/__tests__/**/*.test.ts && vitest run",
-    "test:vitest": "vitest run",
-    "test:vitest:watch": "vitest"
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }