@sanity/ailf-studio 2.2.1 → 2.3.1

package/dist/index.d.ts

@@ -119,10 +119,11 @@ declare const RunTaskEvaluationAction: DocumentActionComponent;
  * ```
  *
  * `ailfStructure` renders filtered entries for `ailf.task`, `ailf.team`,
- * `ailf.featureArea`, and `ailf.report` in place of their default Studio
- * list items, plus a top-level diagnostic for teams whose channel events
- * reference unknown event-type strings. Other document types are preserved
- * at their Studio default via `S.documentTypeListItems().filter(...)`.
+ * `ailf.user`, `ailf.featureArea`, and `ailf.report` in place of their
+ * default Studio list items, plus a top-level diagnostic for teams whose
+ * channel events reference unknown event-type strings. Other document types
+ * are preserved at their Studio default via
+ * `S.documentTypeListItems().filter(...)`.
  * Consumers who already maintain a custom structure can splice individual
  * helpers in via the per-type exports.
  */
@@ -135,9 +136,10 @@ declare const RunTaskEvaluationAction: DocumentActionComponent;
 declare function ailfTaskStructureItem(S: StructureBuilder): ReturnType<StructureBuilder["listItem"]>;
 /**
  * Full structure resolver that replaces the default entries for
- * `ailf.task`, `ailf.team`, `ailf.featureArea`, and `ailf.report` with
- * filtered AILF views, exposes a top-level unknown-events diagnostic,
- * and keeps every other document type list item at its Studio default.
+ * `ailf.task`, `ailf.team`, `ailf.user`, `ailf.featureArea`, and
+ * `ailf.report` with filtered AILF views, exposes a top-level
+ * unknown-events diagnostic, and keeps every other document type list item
+ * at its Studio default.
  */
 declare const ailfStructure: StructureResolver;
 
@@ -512,6 +514,7 @@ declare const featureAreaSchema: {
     preview?: sanity.PreviewConfig<{
         areaId: string;
         description: string;
+        team: string;
     }, Record<string, unknown>> | undefined;
 };
 
@@ -639,6 +642,39 @@ declare const teamSchema: {
     }, Record<string, unknown>> | undefined;
 };
 
+/**
+ * schema/user.ts
+ *
+ * Sanity document schema for `ailf.user` — a per-account user document that
+ * stores self-declared team affiliation (references to `ailf.team`) plus UI
+ * preferences, and is the primary source for dashboard personalization.
+ *
+ * This schema is a deliberate **subset** of the canonical `AilfUser` domain
+ * type (`packages/core/src/types/user.ts`), per D0045 (TS-first domain type →
+ * Zod `satisfies` → Sanity-as-subset; Studio schemas are hand-authored and
+ * never TypeGen-inverted).
+ *
+ * Every field is `readOnly: true`. The dashboard App SDK is the write surface
+ * (lazy `createIfNotExists` + patch via `useApplyDocumentActions`); Studio is
+ * for operator inspection/triage only. `readOnly` is a Studio-UI concern and
+ * does not affect the dashboard's programmatic writes.
+ *
+ * Relationship to D0055: `ailf.user` is the user-side identity/affiliation axis
+ * deferred by the team-entity work — distinct from `area.team` ownership and
+ * `team.notifications[].scope` subscription.
+ *
+ * @see docs/design-docs/user-settings.md § Type-architecture placement
+ */
+declare const userSchema: {
+    type: "document";
+    name: "ailf.user";
+} & Omit<sanity.DocumentDefinition, "preview"> & {
+    preview?: sanity.PreviewConfig<{
+        displayName: string;
+        email: string;
+    }, Record<string, unknown>> | undefined;
+};
+
 /**
  * schema/webhook-config.ts
  *
@@ -1230,4 +1266,4 @@ interface AilfPluginOptions {
  */
 declare const ailfPlugin: sanity.Plugin<void | AilfPluginOptions>;
 
-export { type AilfPluginOptions, ArchiveTaskAction, AssertionInput, CanonicalDocInput, type ComparisonData, type ContentImpactItem, GraduateToNativeAction, HelpDrawer, HelpProvider, MirrorBanner, type PerModelData, type ProvenanceData, ReleasePicker, type ReportDetail, type ReportListItem, RestoreTaskAction, type RunEvaluationActionOptions, RunTaskEvaluationAction, type ScoreItem, type SummaryData, SyncStatusBadge, type TimelineDataPoint, ailfPlugin, ailfStructure, ailfTaskStructureItem, ailfTool, articleSearchQuery, comparisonPairQuery, contentImpactQuery, createRunEvaluationAction, deriveHelpTopic, distinctAreasQuery, distinctModesQuery, distinctPerspectivesQuery, distinctSourcesQuery, distinctTargetDocumentsQuery, distinctTriggersQuery, evalRequestSchema, featureAreaSchema, findTopic, latestReportsQuery, recentDocumentEvalsQuery, referenceSolutionSchema, reportDetailQuery, reportSchema, scoreTimelineQuery, searchTopics, taskSchema, teamSchema, useHelp, webhookConfigSchema };
+export { type AilfPluginOptions, ArchiveTaskAction, AssertionInput, CanonicalDocInput, type ComparisonData, type ContentImpactItem, GraduateToNativeAction, HelpDrawer, HelpProvider, MirrorBanner, type PerModelData, type ProvenanceData, ReleasePicker, type ReportDetail, type ReportListItem, RestoreTaskAction, type RunEvaluationActionOptions, RunTaskEvaluationAction, type ScoreItem, type SummaryData, SyncStatusBadge, type TimelineDataPoint, ailfPlugin, ailfStructure, ailfTaskStructureItem, ailfTool, articleSearchQuery, comparisonPairQuery, contentImpactQuery, createRunEvaluationAction, deriveHelpTopic, distinctAreasQuery, distinctModesQuery, distinctPerspectivesQuery, distinctSourcesQuery, distinctTargetDocumentsQuery, distinctTriggersQuery, evalRequestSchema, featureAreaSchema, findTopic, latestReportsQuery, recentDocumentEvalsQuery, referenceSolutionSchema, reportDetailQuery, reportSchema, scoreTimelineQuery, searchTopics, taskSchema, teamSchema, useHelp, userSchema, webhookConfigSchema };

package/dist/index.js

@@ -530,6 +530,41 @@ var GLOSSARY = {
   triggerCrossRepo: {
     label: "Cross-Repo",
     long: "Cross-repo \u2014 triggered from another repository via the dispatch API. Used when external repos want to validate their docs against AILF tasks."
+  },
+  // -- Variant values (per-test docs condition) ------------------------------
+  variantGold: {
+    label: "Gold",
+    long: "Gold variant \u2014 the relevant docs were injected into the prompt as context. This is the ceiling condition: the best the documentation can do."
+  },
+  variantBaseline: {
+    label: "Baseline",
+    long: "Baseline variant \u2014 no documentation in the prompt. This is the floor condition: what the model already knows from its training data, used as the control for doc lift."
+  },
+  // -- Execution mode values (how the model was driven) ----------------------
+  engineNaive: {
+    label: "Naive",
+    long: "Naive \u2014 the in-house agentic harness with naive prompting. The model runs in an agent loop with no doc-targeting strategy."
+  },
+  engineOptimized: {
+    label: "Optimized",
+    long: "Optimized \u2014 the in-house agentic harness with optimized prompting. The model runs in an agent loop tuned for documentation retrieval."
+  },
+  engineNormal: {
+    label: "Normal",
+    long: "Normal \u2014 a direct vendor-API call. The model produces a single-shot completion with no agent loop."
+  },
+  // -- Status values (per-test outcome) --------------------------------------
+  statusFail: {
+    label: "Fail",
+    long: "Fail \u2014 the model produced no usable output (empty response, API error, or token exhaustion). Distinct from a low score on output that was produced."
+  },
+  statusLowDim: {
+    label: "Low dim",
+    long: "Low dim \u2014 the run produced output but at least one grading dimension scored below 60."
+  },
+  statusOk: {
+    label: "OK",
+    long: "OK \u2014 the run produced output and every grading dimension scored 60 or above."
   }
 };
 
@@ -609,6 +644,17 @@ following:
       "scoring-model"
     ]
   },
+  {
+    "id": "failure-modes",
+    "title": "Failure Modes",
+    "body": "## What this view is for\n\nThe Recommendations view tells you which fixes to make. This view tells you what\nkind of problem you have. It groups the run's weaknesses by the documentation\nissue behind them, so you can see patterns across the whole evaluation rather\nthan one fix at a time. If most of your weak spots are the same kind of problem,\nthat is a signal about how to spend your docs effort.\n\n## What you are looking at\n\nRecent reports show **interpretive cards** drawn from the run's diagnosis:\n\n- **Weakest area** names the single feature area dragging the score down most,\n  the failure mode behind it, and a confidence level with the sample size, so\n  you know how strong the signal is.\n- **Failure mode** highlights one category of problem, which scoring dimension\n  it shows up in, and how often it occurred across the tests that were checked.\n- **Area summary** gives a plain-language read on how an area is doing and why.\n\nOlder reports show a **category breakdown** instead. Each failure category is a\nchip with a count. Selecting a chip lists the gaps in that category, and each\ngap shows an estimated score lift if fixed, a confidence level, a short\nremediation note, and the specific tasks that exposed it. You can click a task\nto jump to it.\n\n## The failure modes\n\nEach weakness is sorted into one of these categories. The category is the\nfastest way to know what kind of work the fix needs:\n\n- **Missing docs**: the doc the model needed does not exist or is not indexed.\n  The fix is to write new documentation.\n- **Incorrect docs**: a doc has a factual error or a wrong example. The fix is\n  to correct it.\n- **Outdated docs**: a doc exists but reflects a previous API surface. The fix\n  is to bring it up to date.\n- **Poor structure**: the information is correct but hard for an agent to find\n  or skim. The fix is to reorganize or clarify.\n- **Model limitation**: the model struggles even with correct docs available.\n  This is not a documentation problem, so treat it as context rather than a\n  to-do.\n- **Unclassified**: the run could not categorize the weakness. Use the linked\n  tasks and the grader's notes to judge it yourself.\n\nDepending on the evaluation mode you may see additional categories, including\nones specific to agent behavior such as tool misuse or missing error handling.\n\n## How to use it\n\nStart with the category that has the most gaps or the highest combined lift. The\ncategory tells you the shape of the work before you open a single page: write,\ncorrect, update, or restructure. Categories that are not documentation problems,\nsuch as model limitation, are worth noting but are not yours to fix in the docs.\n\n## Related views\n\n- **Recommendations** turns these weaknesses into a ranked list of specific\n  edits.\n- **Low-scoring judgments** shows the grader's raw notes on the tests that\n  scored lowest, which is the most granular signal behind any failure mode.\n\n## When this view is empty\n\nIf a report shows no failure modes, the evaluation either classified nothing\nworth flagging or the run predates this view. A clean result here usually means\nthe docs held up across the evaluated tasks.",
+    "source": "docs/help/failure-modes.md",
+    "related": [
+      "recommendations",
+      "scoring-model",
+      "negative-doc-lift"
+    ]
+  },
   {
     "id": "getting-started",
     "title": "Getting Started",
@@ -661,23 +707,183 @@ Click into any report for the full breakdown: per-area scores, diagnostics, and
   {
     "id": "interpreting-diagnostics",
     "title": "Interpreting Diagnostics",
-    "body": "## The diagnostics tab\n\nWhen you open a report and click the **Diagnostics** tab, you see a health\nsummary of your documentation across all feature areas. This is the most\nactionable view in the dashboard \u2014 it tells you exactly where to focus your doc\nimprovement efforts.\n\n## Health categories\n\nFeature areas are grouped into three health bands:\n\n- **Strong (80+)** \u2014 Docs are working well. AI agents produce correct, complete\n  implementations. No action needed unless you see regression.\n- **Needs Attention (70\u201379)** \u2014 Docs are okay but have gaps. There may be\n  specific dimensions (like code correctness or doc coverage) dragging the score\n  down. Worth investigating.\n- **Weak (below 70)** \u2014 Docs are not providing enough support. AI agents\n  consistently struggle with these features. These need priority attention.\n\n## Strengths vs. Issues\n\nThe diagnostics tab has two sub-views:\n\n**Strengths** highlights what's working: high-scoring areas, strong dimensions,\nand areas where agents successfully find and use your docs. Use this to\nunderstand what good looks like in your docs \u2014 and replicate it elsewhere.\n\n**Issues** lists the problems: weak areas, dimensions scoring below 50, negative\ndoc lift, retrieval problems, and (if gap analysis was run) specific\nrecommendations with estimated score lift.\n\n## Key diagnostic signals\n\n| Signal                         | What it means                              | What to do                               |\n| ------------------------------ | ------------------------------------------ | ---------------------------------------- |\n| **Negative doc lift**          | Docs are worse than no docs                | Rewrite or remove the offending docs     |\n| **Large retrieval gap**        | Good docs exist but agents can't find them | Improve page titles, metadata, SEO       |\n| **Low code correctness**       | Agents find the docs but produce bad code  | Add or fix code examples                 |\n| **Low doc coverage**           | The docs don't cover what the task needs   | Write new documentation                  |\n| **Efficiency anomaly (>100%)** | Agents do better without gold docs         | Injected docs may be confusing the model |",
+    "body": "## Reading the health of your docs\n\nA report scores each feature area on how well your documentation lets AI coding\ntools implement that feature. Reading those scores well is what turns a number\ninto a plan: it tells you where the docs are working, where they are not, and\nwhat kind of problem you are dealing with.\n\n## Health bands\n\nEach area's score falls into one of three bands:\n\n- **Strong (80 and above)**: docs are working well. Agents produce correct,\n  complete implementations. No action needed unless you see a regression.\n- **Needs attention (70 to 79)**: docs are okay but have gaps. A specific\n  dimension such as code correctness or doc coverage may be dragging the score\n  down. Worth investigating.\n- **Weak (below 70)**: docs are not providing enough support. Agents\n  consistently struggle with these features. These need priority attention.\n\n## Strong areas are signal too\n\nIt is easy to focus only on what is broken, but the strong areas are worth\nreading. They show what good looks like in your docs: clear structure, accurate\nexamples, the patterns agents can follow. When you fix a weak area, that is the\nbar to copy.\n\n## Key diagnostic signals\n\nA low score has a reason behind it. These signals tell you which reason, and\nwhat to do about it:\n\n| Signal                         | What it means                               | What to do                               |\n| ------------------------------ | ------------------------------------------- | ---------------------------------------- |\n| **Negative doc lift**          | Docs are worse than no docs                 | Rewrite or remove the offending docs     |\n| **Large retrieval gap**        | Good docs exist but agents cannot find them | Improve page titles, metadata, structure |\n| **Low code correctness**       | Agents find the docs but produce bad code   | Add or fix code examples                 |\n| **Low doc coverage**           | The docs do not cover what the task needs   | Write new documentation                  |\n| **Efficiency anomaly (>100%)** | Agents do better without the docs           | Injected docs may be confusing the model |\n\n## Where to go next\n\nWhen you know which areas are weak and why, the **Recommendations** view turns\nthat into a ranked list of specific edits, and the **Failure modes** view groups\nthe weaknesses by the kind of documentation problem behind them.",
     "source": "docs/help/interpreting-diagnostics.md",
     "related": [
-      "scoring-model",
-      "weaknesses-recommendations"
+      "recommendations",
+      "failure-modes",
+      "scoring-model"
     ]
   },
   {
     "id": "reading-score-trends",
-    "title": "Reading Score Trends",
-    "body": "## What the timeline shows\n\nThe Score Timeline view plots your AI Literacy Score over time. Each point is an\nevaluation run \u2014 a snapshot of how well your docs support AI agents at that\nmoment.\n\n## What to look for\n\n**Upward trends** after doc changes confirm that your improvements are working.\nIf you rewrote a GROQ guide and the GROQ area score climbs in the next run,\nthat's direct evidence of impact.\n\n**Sudden drops** usually mean something changed: a doc was deleted, an API\nchanged without a doc update, or a new task was added that exposes a gap.\n\n**Flat lines** mean stability \u2014 neither improving nor regressing. This is fine\nfor mature areas but concerning for areas you're actively working on.\n\n## Meaningful change vs. noise\n\nSmall fluctuations (\xB12\u20133 points) between runs are normal \u2014 they come from LLM\nnon-determinism and grader variance. Focus on changes of **5+ points** sustained\nacross multiple runs. The comparison view applies a noise threshold to help\ndistinguish real changes from statistical noise.\n\n## Filtering the timeline\n\nUse the filters to focus on specific evaluation modes (baseline vs. full),\nspecific doc sources (production vs. branch), or specific feature areas.\nComparing the same area across modes reveals whether a problem is in the docs\nthemselves (baseline score) or in how agents find them (agentic score).",
+    "title": "Reading the Analytics View",
+    "body": `## What this view answers
+
+The Analytics view is built around one question: **did your doc changes move the
+score, and why?** Rather than open on a chart and leave you to find the story,
+it leads with the answer \u2014 a plain-language verdict and the areas that moved
+most \u2014 then lets you drill down into the evidence.
+
+## The control bar
+
+The top row picks what you're looking at:
+
+- **Metric** \u2014 which number to track (composite score, doc lift, retrieval gap,
+  and so on).
+- **Break down by** \u2014 how to split it (feature area, team, model, source).
+- **Bucket** \u2014 how to group runs over time (per run, per day).
+- **Range** \u2014 how far back to look (for example, the last 30 days).
+
+The second row holds the active **filter chips** \u2014 use _Add filter_ to scope to
+a team, source, or mode \u2014 and a scope hint (reports in scope vs. total). Every
+knob and filter is saved in the URL, so a shared link reproduces exactly what
+you see. Use **Copy link** to grab it.
+
+## Overall \u2014 the read
+
+The **verdict strip** is the headline. In plain language it says whether docs
+are pulling ahead or slipping, and shows the headline metric with its change (\u0394)
+since the start of the range, a model \u2192 agent \u2192 docs decomposition bar, and a
+coverage cell (how many reports and high-confidence groups are in scope).
+
+## Movers
+
+The **movers board** leads with the top **Improved** and **Regressed** areas as
+cards \u2014 not the average. Each card shows the area, its value and \u0394, a
+decomposition bar, the release that most likely caused the move, and a
+confidence read. A low-confidence **watch** callout flags big swings backed by
+too few runs: watch them, don't celebrate them yet.
+
+Click a mover card to reveal and decompose that series in the evidence chart.
+
+## The evidence
+
+The **focus chart** has two modes:
+
+- **Compare** plots the selected series over time. It defaults to a focused set
+  (the movers plus the highest-volume areas) with a _show all_ expansion, and
+  draws release markers inline.
+- **Decompose** shows the ceiling / floor / actual band for a single series,
+  with causal story cards anchored to each release marker (for example, _"Docs
+  +3 ~5 \u22121 \u2192 doc-lift +8 measured around this release"_).
+
+Decompose is offered for the composite metric broken down by feature area \u2014 the
+case where the model \u2192 agent \u2192 docs story is meaningful.
+
+## The breakdown table
+
+One row per area (or per whatever you broke down by), each with an inline
+decomposition bar, a sparkline, confidence, \u0394, "docs add," and a report count.
+Sort any column, and click a row to cross-highlight it in the chart. Export the
+table to CSV.
+
+## Meaningful change vs. noise
+
+Small movements between runs are normal \u2014 they come from model non-determinism
+and grader variance. This view leans on **confidence** (how many runs back a
+number) and the **movers ranking** rather than a single \xB1point threshold: trust
+a sustained move in a high-confidence area over a large swing in a
+low-confidence one. The low-confidence watch exists precisely to stop you
+over-reading thin data.
+
+## Measured, not invented
+
+The causal story is computed from real data, never fabricated. Release markers
+come from the doc-change counts already recorded in each report, and the
+"measured around this release" doc-lift effect is derived from the real ceiling
+\u2212 floor series around the marker. Per-area prose ("the editor API changed") is
+intentionally not shown \u2014 the data carries change counts, not hand-written
+explanations.`,
     "source": "docs/help/reading-score-trends.md",
     "related": [
       "scoring-model",
+      "doc-lift",
       "comparing-runs"
     ]
   },
+  {
+    "id": "recommendations",
+    "title": "Recommendations",
+    "body": `## What this view is for
+
+This is the "what do I fix" view. The scores tell you how well your
+documentation supports AI coding tools. This view turns those scores into a
+ranked list of specific changes, so you can spend your time on the edits that
+should move the score the most.
+
+Everything here comes from the same evaluation run you are looking at, and it
+points at your own documentation pages rather than giving generic advice.
+
+## What you are looking at
+
+Recent reports show a set of **diagnosis cards**. Each card answers one question
+about the run.
+
+**Top recommendations** is the main card. It opens with a short summary, then
+lists a few suggested changes ranked by priority. Each suggestion has:
+
+- A **priority** tag of high, medium, or low that tells you what to do first.
+- A **title** that names the change in one line.
+- A **description** of the specific fix, usually quoting the exact symbol,
+  query, or pattern involved.
+- A **doc reference** showing which page, and the section when it is known, the
+  change applies to. Every reference points to a real page that was part of this
+  run, so you can open it and start editing.
+
+You may also see supporting cards:
+
+- **Doc attribution spotlight** shows which documentation pages most influenced
+  the results, and whether each one helped or hurt. Use it to confirm a
+  recommendation is pointing at the right page.
+- **Low-confidence attribution** lists results where the link between a doc and
+  an outcome was uncertain. Treat anything flagged here as a lead to verify, not
+  a settled conclusion.
+- **Regression vs baseline** appears when you are comparing against an earlier
+  run. It shows which areas moved up or down and the likely reason for each
+  change.
+
+## How to use it
+
+Work top down. Start with the high-priority suggestions, open the referenced
+page, and make the change. Priority reflects how much each change is expected to
+help, so the top of the list is usually where your effort goes furthest.
+
+The recommendations are written by a model that reads this run's results. They
+are grounded in your actual docs and cannot reference a page that was not in the
+run, but they are still suggestions. Read the linked page before acting, and use
+the confidence signals to decide how much to trust each item.
+
+## Where this comes from
+
+A recommendation is the end of a chain: a test scored low, the grader said why,
+the run classified that into a failure mode, and this view proposes the edit. If
+you want to see the failure modes themselves, grouped by category, open the
+**Failure modes** view. If you want the grader's raw notes on the lowest scores,
+open the **Low-scoring judgments** view.
+
+## Older reports
+
+Reports created before the diagnosis cards shipped show a simpler list instead.
+Each row names a feature area, the failure mode behind it, an estimated score
+lift if you fix it, a confidence level, and the tasks that exposed the gap. The
+estimated lift is conservative. It assumes fixing the gap raises the weak
+dimension only to the median of the others, so the real improvement can be
+higher.
+
+## When this view is empty
+
+If a report shows no recommendations, the evaluation either ran and found
+nothing worth flagging, or the run predates this feature. A score with no
+recommendations is usually a good sign, because it means the docs held up across
+the evaluated tasks.`,
+    "source": "docs/help/recommendations.md",
+    "related": [
+      "failure-modes",
+      "interpreting-diagnostics",
+      "scoring-model"
+    ]
+  },
   {
     "id": "retrieval-gap",
     "title": "Retrieval Gap & Infrastructure Efficiency",
@@ -700,17 +906,6 @@ Click into any report for the full breakdown: per-area scores, diagnostics, and
       "eval-modes"
     ]
   },
-  {
-    "id": "weaknesses-recommendations",
-    "title": "Weaknesses & Recommendations",
-    "body": "## Understanding weaknesses\n\nThe Issues sub-tab in Diagnostics lists every area or dimension that scored\nbelow threshold. Each weakness entry shows:\n\n- **The feature area** \u2014 Which product feature is affected (e.g., GROQ,\n  Functions, Webhooks).\n- **The bottleneck dimension** \u2014 Which scoring dimension is dragging the area\n  down: task completion, code correctness, or doc coverage.\n- **The score** \u2014 How far below threshold the dimension scored.\n\n## Gap analysis recommendations\n\nWhen an evaluation runs with gap analysis enabled, the dashboard shows\n**prioritized recommendations** \u2014 specific actions ranked by estimated impact.\n\nEach recommendation includes:\n\n- **Failure mode** \u2014 The type of doc problem identified:\n  - `missing-docs` \u2014 The functionality isn't documented at all.\n  - `incorrect-docs` \u2014 The docs contain factual errors.\n  - `outdated-docs` \u2014 The docs describe an old API version or pattern.\n  - `poor-structure` \u2014 The docs exist but are hard to find or understand.\n- **Estimated lift** \u2014 How many score points fixing this gap would add. Based on\n  raising the bottleneck dimension to the median of non-bottleneck dimensions.\n  Conservative estimate \u2014 actual improvement may be higher.\n- **Confidence** \u2014 How sure the analysis is about this diagnosis (high, medium,\n  or low).\n- **Affected tasks** \u2014 Which specific evaluation tasks exposed this gap.\n\n## Diagnosis cards\n\nEvery published report now carries a **diagnosis artifact** \u2014 a set of cards\nproduced by the post-pipeline hook (`ailf interpret`). The Studio diagnosis\npanel renders these cards directly; the dashboard's Recommendations and\nFailure-modes panels migrate to the same source in a follow-up.\n\nThe hook runs by default for every pipeline invocation. To opt out for a single\nrun, pass `--no-summary`; to opt out in CI, set `AILF_INTERPRET_ON_RUN=0` in the\nworkflow env block; to opt out project-wide, set `summary.onRun: never` in\n`.ailf/config.yaml`.\n\n## Low-scoring judgments\n\nBelow the recommendations, you'll find the **grader's explanations** for tests\nthat scored below 70. These are the raw assessments from the grading model\nexplaining exactly what went wrong \u2014 missing API calls, incorrect patterns,\nhallucinated features, etc.\n\nEach judgment shows the task, the dimension, the score, and the grader's natural\nlanguage reason. These are the most granular diagnostic signal available and\noften point directly to the doc section that needs fixing.",
-    "source": "docs/help/weaknesses-recommendations.md",
-    "related": [
-      "interpreting-diagnostics",
-      "scoring-model",
-      "negative-doc-lift"
-    ]
-  },
   {
     "id": "how-agents-work",
     "title": "How AI Agents Find Documentation",
@@ -734,7 +929,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 Retrieval 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 \u0394**\n: Change in overall score between the two runs. Positive means the experiment scored higher.\n\n**Actual \u0394**\n: Change in actual (agent-retrieved) score between runs. Positive means agents did better.\n\n**Ret. Gap \u0394**\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 \u0394**\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**Strong (80+)**\n: Feature areas scoring 80 or above. The docs are working well for these features \u2014 AI agents produce correct, complete implementations.\n\n**Needs Attention (70\u201379)**\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**Weak (<70)**\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**\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 Performance**\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**Dimension 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**\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**Unique Doc Slugs**\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 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**\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**\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**Task Completion \u0394**\n: Change in task completion between runs. Positive means implementations are more complete.\n\n**Code Correctness \u0394**\n: Change in code correctness between runs. Positive means better code quality.\n\n**Doc Coverage \u0394**\n: Change in doc coverage between runs. Positive means the docs are providing more useful information.\n\n**Area \u0394**\n: Score change for this area compared to the previous evaluation run.\n\n**Production**\n: Production source \u2014 docs fetched from the live production dataset. Scores reflect what real users and AI agents experience today.\n\n**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**Local**\n: Local source \u2014 docs fetched from local files or a local dev server. Useful for testing doc changes before pushing.\n\n**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**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**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**Baseline**\n: Baseline mode \u2014 tests the model with gold-standard docs injected directly. Measures ceiling performance (best the docs can do).\n\n**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**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**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**Debug**\n: Debug mode \u2014 a diagnostic run for pipeline development. May use non-standard configurations or limited task sets.\n\n**Manual**\n: Manually triggered \u2014 someone ran the evaluation pipeline by hand, either locally or via the Studio UI.\n\n**CI**\n: CI-triggered \u2014 the evaluation ran automatically as part of a pull request or merge pipeline.\n\n**Scheduled**\n: Scheduled \u2014 the evaluation ran on a recurring schedule (e.g. nightly or weekly) to track score trends over time.\n\n**Webhook**\n: Webhook-triggered \u2014 a content change in Sanity triggered the evaluation automatically. Helps catch doc regressions early.\n\n**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 Retrieval 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 \u0394**\n: Change in overall score between the two runs. Positive means the experiment scored higher.\n\n**Actual \u0394**\n: Change in actual (agent-retrieved) score between runs. Positive means agents did better.\n\n**Ret. Gap \u0394**\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 \u0394**\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**Strong (80+)**\n: Feature areas scoring 80 or above. The docs are working well for these features \u2014 AI agents produce correct, complete implementations.\n\n**Needs Attention (70\u201379)**\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**Weak (<70)**\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**\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 Performance**\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**Dimension 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**\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**Unique Doc Slugs**\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 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**\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**\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**Task Completion \u0394**\n: Change in task completion between runs. Positive means implementations are more complete.\n\n**Code Correctness \u0394**\n: Change in code correctness between runs. Positive means better code quality.\n\n**Doc Coverage \u0394**\n: Change in doc coverage between runs. Positive means the docs are providing more useful information.\n\n**Area \u0394**\n: Score change for this area compared to the previous evaluation run.\n\n**Production**\n: Production source \u2014 docs fetched from the live production dataset. Scores reflect what real users and AI agents experience today.\n\n**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**Local**\n: Local source \u2014 docs fetched from local files or a local dev server. Useful for testing doc changes before pushing.\n\n**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**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**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**Baseline**\n: Baseline mode \u2014 tests the model with gold-standard docs injected directly. Measures ceiling performance (best the docs can do).\n\n**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**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**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**Debug**\n: Debug mode \u2014 a diagnostic run for pipeline development. May use non-standard configurations or limited task sets.\n\n**Manual**\n: Manually triggered \u2014 someone ran the evaluation pipeline by hand, either locally or via the Studio UI.\n\n**CI**\n: CI-triggered \u2014 the evaluation ran automatically as part of a pull request or merge pipeline.\n\n**Scheduled**\n: Scheduled \u2014 the evaluation ran on a recurring schedule (e.g. nightly or weekly) to track score trends over time.\n\n**Webhook**\n: Webhook-triggered \u2014 a content change in Sanity triggered the evaluation automatically. Helps catch doc regressions early.\n\n**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.\n\n**Gold**\n: Gold variant \u2014 the relevant docs were injected into the prompt as context. This is the ceiling condition: the best the documentation can do.\n\n**Baseline**\n: Baseline variant \u2014 no documentation in the prompt. This is the floor condition: what the model already knows from its training data, used as the control for doc lift.\n\n**Naive**\n: Naive \u2014 the in-house agentic harness with naive prompting. The model runs in an agent loop with no doc-targeting strategy.\n\n**Optimized**\n: Optimized \u2014 the in-house agentic harness with optimized prompting. The model runs in an agent loop tuned for documentation retrieval.\n\n**Normal**\n: Normal \u2014 a direct vendor-API call. The model produces a single-shot completion with no agent loop.\n\n**Fail**\n: Fail \u2014 the model produced no usable output (empty response, API error, or token exhaustion). Distinct from a low score on output that was produced.\n\n**Low dim**\n: Low dim \u2014 the run produced output but at least one grading dimension scored below 60.\n\n**OK**\n: OK \u2014 the run produced output and every grading dimension scored 60 or above.",
     "source": "packages/shared/src/glossary.ts",
     "tags": [
       "reference",
@@ -1296,16 +1491,22 @@ var featureAreaSchema = defineType2({
   ],
   name: "ailf.featureArea",
   preview: {
-    prepare({ areaId, description }) {
+    // `team` derefs the owning-team reference one hop to its displayName,
+    // so the area list shows ownership at a glance (the dataset-level
+    // "Unowned areas" diagnostic lives in structure.ts).
+    prepare({ areaId, description, team }) {
       const id = areaId !== null && typeof areaId === "object" && "current" in areaId ? areaId.current : void 0;
+      const idStr = typeof id === "string" ? id : "";
+      const teamStr = typeof team === "string" ? team : "";
       return {
-        subtitle: typeof id === "string" ? id : "",
+        subtitle: teamStr ? `${idStr} \xB7 ${teamStr}` : idStr,
         title: typeof description === "string" ? description : "Feature Area"
       };
     },
     select: {
       areaId: "areaId",
-      description: "description"
+      description: "description",
+      team: "team.displayName"
     }
   },
   title: "AILF Feature Area",
@@ -4409,16 +4610,97 @@ var teamSchema = defineType6({
   type: "document"
 });
 
+// src/schema/user.ts
+import { defineArrayMember as defineArrayMember2, defineField as defineField7, defineType as defineType7 } from "sanity";
+var userSchema = defineType7({
+  fields: [
+    defineField7({
+      description: "Sanity account id (CurrentUser.id) \u2014 the stable, globally-unique key. Mirrored as a field so GROQ can join/filter; the document _id is the deterministic `ailf.user.${sanityUserId}`.",
+      name: "sanityUserId",
+      readOnly: true,
+      title: "Sanity User ID",
+      type: "string"
+    }),
+    defineField7({
+      description: "Denormalized email for display / joins (lowercased on write).",
+      name: "email",
+      readOnly: true,
+      title: "Email",
+      type: "string"
+    }),
+    defineField7({
+      description: "Display-name snapshot from CurrentUser.name.",
+      name: "displayName",
+      readOnly: true,
+      title: "Display Name",
+      type: "string"
+    }),
+    defineField7({
+      description: "Self-declared team affiliation \u2014 drives dashboard personalization only. References to ailf.team documents in the same dataset.",
+      name: "teams",
+      of: [
+        defineArrayMember2({
+          to: [{ type: "ailf.team" }],
+          type: "reference"
+        })
+      ],
+      readOnly: true,
+      title: "Teams",
+      type: "array"
+    }),
+    defineField7({
+      description: "Per-user UI personalization.",
+      fields: [
+        defineField7({
+          description: "The user's default team \u2014 one of `teams`. Distinct from `teams` so 'which team's view do I default to' can differ from 'all teams I affiliate with'. The slug consumers need is derived in GROQ.",
+          name: "primaryTeam",
+          readOnly: true,
+          title: "Primary Team",
+          to: [{ type: "ailf.team" }],
+          type: "reference"
+        })
+      ],
+      name: "preferences",
+      readOnly: true,
+      title: "Preferences",
+      type: "object"
+    }),
+    defineField7({
+      description: "ISO 8601 UTC \u2014 stamped on each save by the dashboard.",
+      name: "updatedAt",
+      readOnly: true,
+      title: "Updated At",
+      type: "datetime"
+    })
+  ],
+  name: "ailf.user",
+  preview: {
+    prepare({ displayName, email }) {
+      const title = typeof displayName === "string" && displayName ? displayName : typeof email === "string" && email ? email : "(unknown user)";
+      return {
+        subtitle: typeof email === "string" ? email : "",
+        title
+      };
+    },
+    select: {
+      displayName: "displayName",
+      email: "email"
+    }
+  },
+  title: "AILF User",
+  type: "document"
+});
+
 // src/schema/webhook-config.ts
-import { ALL_FIELDS_GROUP as ALL_FIELDS_GROUP7, defineField as defineField7, defineType as defineType7 } from "sanity";
-var webhookConfigSchema = defineType7({
+import { ALL_FIELDS_GROUP as ALL_FIELDS_GROUP7, defineField as defineField8, defineType as defineType8 } from "sanity";
+var webhookConfigSchema = defineType8({
   groups: [
     { name: "main", title: "Main", default: true },
     { name: "optional", title: "Optional" },
     ALL_FIELDS_GROUP7
   ],
   fields: [
-    defineField7({
+    defineField8({
       description: "When enabled, publishing articles will automatically trigger AI Literacy evaluations for affected feature areas.",
       group: ["main", "all-fields"],
       initialValue: false,
@@ -4426,7 +4708,7 @@ var webhookConfigSchema = defineType7({
       title: "Evaluate on Publish",
       type: "boolean"
     }),
-    defineField7({
+    defineField8({
       description: "Which evaluation mode to use for webhook-triggered evaluations.",
       group: ["main", "all-fields"],
       initialValue: "baseline",
@@ -4442,7 +4724,7 @@ var webhookConfigSchema = defineType7({
       title: "Evaluation Mode",
       type: "string"
     }),
-    defineField7({
+    defineField8({
       description: "Maximum evaluations per day. Prevents runaway costs from rapid editing.",
       group: ["main", "all-fields"],
       initialValue: 20,
@@ -4451,7 +4733,7 @@ var webhookConfigSchema = defineType7({
       type: "number",
       validation: (rule) => rule.min(1).max(100)
     }),
-    defineField7({
+    defineField8({
       description: "Seconds to wait after the last edit before dispatching. Coalesces rapid edits into a single evaluation.",
       group: ["optional", "all-fields"],
       initialValue: 300,
@@ -4460,7 +4742,7 @@ var webhookConfigSchema = defineType7({
       type: "number",
       validation: (rule) => rule.min(10).max(3600)
     }),
-    defineField7({
+    defineField8({
       description: "Specific feature areas to evaluate. Leave empty to evaluate all affected areas automatically.",
       group: ["optional", "all-fields"],
       name: "areas",
@@ -4468,7 +4750,7 @@ var webhookConfigSchema = defineType7({
       title: "Area Filter",
       type: "array"
     }),
-    defineField7({
+    defineField8({
       description: "Slack webhook URL for notifications about webhook-triggered evaluations.",
       group: ["optional", "all-fields"],
       name: "notifySlack",
@@ -4615,7 +4897,7 @@ function deriveHelpTopic(routerState) {
   if (routerState.reportId) {
     switch (routerState.tab) {
       case "diagnostics":
-        return routerState.subTab === "strengths" ? "interpreting-diagnostics" : "weaknesses-recommendations";
+        return routerState.subTab === "strengths" ? "interpreting-diagnostics" : "recommendations";
       case "activity":
         return "how-agents-work";
       default:
@@ -15813,6 +16095,21 @@ function ailfTeamsStructureItem(S) {
     ])
   );
 }
+function ailfUsersStructureItem(S) {
+  return S.listItem().id("ailfUsers").title("Users").child(
+    S.list().id("ailfUsersViews").title("Users").items([
+      S.listItem().id("allUsers").title("All users").child(
+        S.documentTypeList("ailf.user").id("ailfUsersAll").title("All users")
+      ),
+      S.divider(),
+      S.listItem().id("usersWithoutTeams").title("\u26A0 Users without teams").icon(WarningOutlineIcon5).child(
+        S.documentTypeList("ailf.user").id("ailfUsersWithoutTeams").title("\u26A0 Users without teams").apiVersion(API_VERSION).filter(
+          '_type == "ailf.user" && (!defined(teams) || count(teams) == 0)'
+        )
+      )
+    ])
+  );
+}
 function ailfAreasStructureItem(S) {
   return S.listItem().id("ailfAreas").title("Areas").child(
     S.list().id("ailfAreasViews").title("Areas").items([
@@ -15851,13 +16148,14 @@ function ailfChannelsWithUnknownEventsItem(S) {
 var ailfStructure = (S) => S.list().id("root").title("Content").items([
   ailfTaskStructureItem(S),
   ailfTeamsStructureItem(S),
+  ailfUsersStructureItem(S),
   ailfAreasStructureItem(S),
   ailfReportsStructureItem(S),
   ailfChannelsWithUnknownEventsItem(S),
   S.divider(),
   ...S.documentTypeListItems().filter((listItem) => {
     const id = listItem.getId();
-    return id !== "ailf.task" && id !== "ailf.team" && id !== "ailf.featureArea" && id !== "ailf.report";
+    return id !== "ailf.task" && id !== "ailf.team" && id !== "ailf.user" && id !== "ailf.featureArea" && id !== "ailf.report";
   })
 ]);
 
@@ -16207,6 +16505,7 @@ var ailfPlugin = definePlugin((options) => ({
       reportSchema,
       taskSchema,
       teamSchema,
+      userSchema,
       webhookConfigSchema
     ]
   },
@@ -16252,5 +16551,6 @@ export {
   taskSchema,
   teamSchema,
   useHelp,
+  userSchema,
   webhookConfigSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ailf-studio",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "AI Literacy Framework — Sanity Studio dashboard plugin",
   "type": "module",
   "license": "MIT",