@sanity/ailf 4.1.0 → 4.2.0

package/dist/sanity/document-renderers.d.ts

@@ -0,0 +1,68 @@
+/**
+ * document-renderers.ts
+ *
+ * Renderer registry that turns a Sanity document fetched by `_id` into
+ * Markdown for inclusion in a literacy task's grader context.
+ *
+ * The resolver fetches docs without an `_type` filter and dispatches here.
+ * Two tiers of fidelity:
+ *
+ *   1. Registered renderers (high fidelity) — `article`, `typesReference`.
+ *      Hand-written for the document shapes we care about most.
+ *   2. Default renderer (best effort) — walks the doc, flattens portable-text
+ *      fields, surfaces top-level scalars, follows references one level deep,
+ *      skips framework-internal fields. Lets pinning a `marketingPage`,
+ *      `glossaryEntry`, etc. work without AILF code changes.
+ *
+ * Adding a new high-fidelity renderer: implement a `DocumentRenderer` and
+ * register it in `BUILT_IN_RENDERERS` keyed by `_type`.
+ */
+/**
+ * A Sanity document plus any references we've already resolved for it.
+ * The resolver fetches the doc once and may include common deref payloads
+ * (e.g. `latestVersion->{...}` for typesReference) so renderers don't need
+ * to issue additional client.fetch calls themselves.
+ */
+export interface DocumentForRender {
+    _id: string;
+    _type: string;
+    [key: string]: unknown;
+}
+export interface RenderContext {
+    /**
+     * Async URL fetcher for renderers that need to follow `sanity.fileAsset`
+     * URLs (e.g. typedoc JSON for `typesReference` docs). Returns the raw
+     * body text or `null` on failure.
+     */
+    fetchUrl?: (url: string) => Promise<string | null>;
+    /**
+     * Soft cap on rendered content length, in bytes. Renderers should respect
+     * this and append a truncation notice rather than blow up grader context.
+     */
+    maxBytes?: number;
+}
+export interface RenderResult {
+    /** The rendered Markdown. Empty string is permitted but produces a warn. */
+    content: string;
+    /**
+     * The fidelity tier used. Resolvers can log differently based on this:
+     *   - "high"    — a registered renderer ran
+     *   - "default" — fell through to the generic walker (info log)
+     */
+    fidelity: "high" | "default";
+    /**
+     * Stable display slug for this document. Articles use `slug.current`;
+     * other types fall back to a `<_type>:<_id>` form when no slug exists.
+     * Surfaces in `DocContext.slugs` for retrieval-metric attribution.
+     */
+    slug: string;
+}
+export type DocumentRenderer = (doc: DocumentForRender, ctx: RenderContext) => Promise<RenderResult> | RenderResult;
+/**
+ * Render a document using the registered renderer for its `_type`, falling
+ * back to the default walker. The returned `fidelity` flag tells callers
+ * whether to emit the "info: dedicated renderer would help" log.
+ */
+export declare function renderDocument(doc: DocumentForRender, ctx?: RenderContext): Promise<RenderResult>;
+/** Exported for tests and consumers that want the registered set. */
+export declare const REGISTERED_RENDERER_TYPES: string[];

package/dist/sanity/document-renderers.js

@@ -0,0 +1,221 @@
+/**
+ * document-renderers.ts
+ *
+ * Renderer registry that turns a Sanity document fetched by `_id` into
+ * Markdown for inclusion in a literacy task's grader context.
+ *
+ * The resolver fetches docs without an `_type` filter and dispatches here.
+ * Two tiers of fidelity:
+ *
+ *   1. Registered renderers (high fidelity) — `article`, `typesReference`.
+ *      Hand-written for the document shapes we care about most.
+ *   2. Default renderer (best effort) — walks the doc, flattens portable-text
+ *      fields, surfaces top-level scalars, follows references one level deep,
+ *      skips framework-internal fields. Lets pinning a `marketingPage`,
+ *      `glossaryEntry`, etc. work without AILF code changes.
+ *
+ * Adding a new high-fidelity renderer: implement a `DocumentRenderer` and
+ * register it in `BUILT_IN_RENDERERS` keyed by `_type`.
+ */
+import { toMarkdown } from "./portable-text.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_BYTES = 30_000;
+const SKIP_FIELDS = new Set([
+    "_createdAt",
+    "_id",
+    "_rev",
+    "_system",
+    "_type",
+    "_updatedAt",
+    "_key",
+]);
+function isPortableTextArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        typeof value[0] === "object" &&
+        value[0] !== null &&
+        "_type" in value[0]);
+}
+function truncate(content, max) {
+    if (content.length <= max)
+        return content;
+    return (content.slice(0, max) +
+        `\n\n*[content truncated — ${content.length - max} more bytes omitted]*`);
+}
+function slugForDoc(doc) {
+    const slugField = doc.slug;
+    if (typeof slugField === "object" &&
+        slugField !== null &&
+        "current" in slugField &&
+        typeof slugField.current === "string") {
+        return slugField.current;
+    }
+    if (typeof slugField === "string")
+        return slugField;
+    return `${doc._type}:${doc._id}`;
+}
+function articleRenderer(doc) {
+    const title = doc.title ?? "(untitled)";
+    const description = doc.description;
+    const section = doc.section;
+    const content = doc.content;
+    const sectionLabel = section?.title ? `Section: ${section.title}\n` : "";
+    const desc = description ? `${description}\n\n` : "";
+    const markdown = toMarkdown(content ?? []);
+    return {
+        content: `## ${title}\n\n${sectionLabel}${desc}${markdown}`,
+        fidelity: "high",
+        slug: slugForDoc(doc),
+    };
+}
+async function typesReferenceRenderer(doc, ctx) {
+    const title = doc.title ?? "(untitled)";
+    const slug = slugForDoc(doc);
+    const library = doc.library;
+    const latestVersion = doc.latestVersion;
+    const asset = latestVersion?.attachment?.asset;
+    const max = ctx.maxBytes ?? DEFAULT_MAX_BYTES;
+    const lines = [];
+    lines.push(`## ${title}`, "");
+    lines.push(`Slug: \`${slug}\``);
+    if (library?.npmName)
+        lines.push(`Package: \`${library.npmName}\``);
+    if (latestVersion?.semver)
+        lines.push(`Version: \`${latestVersion.semver}\``);
+    if (latestVersion?.date)
+        lines.push(`Released: ${latestVersion.date}`);
+    lines.push("");
+    if (!asset?.url) {
+        lines.push("*[no attached type definitions found — resolver could not locate `latestVersion.attachment.asset.url`]*");
+        return { content: lines.join("\n"), fidelity: "high", slug };
+    }
+    if (!ctx.fetchUrl) {
+        lines.push(`*[type definitions live at ${asset.url} — fetcher not configured to retrieve attachments]*`);
+        return { content: lines.join("\n"), fidelity: "high", slug };
+    }
+    const body = await ctx.fetchUrl(asset.url);
+    if (body === null) {
+        lines.push(`*[failed to fetch type definitions from ${asset.url}]*`);
+        return { content: lines.join("\n"), fidelity: "high", slug };
+    }
+    const filename = asset.originalFilename ?? "types.json";
+    const lang = filename.endsWith(".json") ? "json" : "";
+    lines.push(`### Type definitions (${filename})`, "");
+    lines.push("```" + lang);
+    // Reserve ~200 bytes for the fence + trailing notice
+    lines.push(truncate(body, Math.max(0, max - 200)));
+    lines.push("```");
+    return { content: lines.join("\n"), fidelity: "high", slug };
+}
+// ---------------------------------------------------------------------------
+// formatDefault — generic walker for any unknown `_type`.
+//
+// Walks top-level fields, renders portable-text arrays as Markdown, surfaces
+// scalars as labeled key/value lines, and follows resolved references one
+// level deep. The output is "best effort" — not as tight as a hand-written
+// renderer, but feeds the LLM grader real content for any pinned doc type.
+// ---------------------------------------------------------------------------
+function renderScalar(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return null;
+}
+function renderField(key, value, depth = 0) {
+    if (value === null || value === undefined)
+        return null;
+    if (SKIP_FIELDS.has(key))
+        return null;
+    const indent = "  ".repeat(depth);
+    if (isPortableTextArray(value)) {
+        const md = toMarkdown(value);
+        if (!md.trim())
+            return null;
+        return `${indent}**${key}:**\n\n${md}`;
+    }
+    // Sanity slug field: { _type: "slug", current: "…" }
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value._type === "slug") {
+        const current = value.current;
+        if (typeof current === "string")
+            return `${indent}**${key}:** \`${current}\``;
+        return null;
+    }
+    const scalar = renderScalar(value);
+    if (scalar !== null)
+        return `${indent}**${key}:** ${scalar}`;
+    // Single-level deref: a previously-resolved reference shows up as an
+    // object with its own `_id`/`_type` (the projection joined it in). Walk
+    // its fields one level deep.
+    if (typeof value === "object" &&
+        !Array.isArray(value) &&
+        depth === 0 &&
+        value._id !== undefined) {
+        const inner = Object.entries(value)
+            .map(([k, v]) => renderField(k, v, depth + 1))
+            .filter((line) => line !== null);
+        if (inner.length === 0)
+            return null;
+        return `${indent}**${key}:**\n${inner.join("\n")}`;
+    }
+    if (Array.isArray(value)) {
+        const items = value
+            .map((item, i) => renderField(String(i), item, depth + 1))
+            .filter((line) => line !== null);
+        if (items.length === 0)
+            return null;
+        return `${indent}**${key}:**\n${items.join("\n")}`;
+    }
+    return null;
+}
+function defaultRenderer(doc) {
+    const title = doc.title ?? `(${doc._type})`;
+    const slug = slugForDoc(doc);
+    const lines = [`## ${title}`, "", `Type: \`${doc._type}\``];
+    if (slug !== `${doc._type}:${doc._id}`)
+        lines.push(`Slug: \`${slug}\``);
+    lines.push("");
+    const fieldLines = [];
+    for (const [key, value] of Object.entries(doc)) {
+        if (key === "title")
+            continue;
+        if (key === "slug" && slug !== `${doc._type}:${doc._id}`)
+            continue;
+        const rendered = renderField(key, value);
+        if (rendered !== null)
+            fieldLines.push(rendered);
+    }
+    if (fieldLines.length > 0) {
+        lines.push(...fieldLines);
+    }
+    else {
+        lines.push("*[no renderable content — all fields were null, framework metadata, or unrecognized shapes]*");
+    }
+    return { content: lines.join("\n"), fidelity: "default", slug };
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const BUILT_IN_RENDERERS = {
+    article: articleRenderer,
+    typesReference: typesReferenceRenderer,
+};
+/**
+ * Render a document using the registered renderer for its `_type`, falling
+ * back to the default walker. The returned `fidelity` flag tells callers
+ * whether to emit the "info: dedicated renderer would help" log.
+ */
+export async function renderDocument(doc, ctx = {}) {
+    const renderer = BUILT_IN_RENDERERS[doc._type];
+    if (renderer)
+        return renderer(doc, ctx);
+    return defaultRenderer(doc);
+}
+/** Exported for tests and consumers that want the registered set. */
+export const REGISTERED_RENDERER_TYPES = Object.keys(BUILT_IN_RENDERERS).sort();

package/dist/sanity/queries.d.ts

@@ -87,6 +87,27 @@ export declare const ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY = "\n  *[_type == \"
  * @param $ids — array of document ID strings
  */
 export declare const ARTICLES_BY_IDS_QUERY = "\n  *[_type == \"article\"\n    && _id in $ids\n  ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+/**
+ * Fetch arbitrary documents by their `_id` — no `_type` filter.
+ *
+ * Used by id-ref resolution so authors can pin any document type
+ * (`article`, `typesReference`, `marketingPage`, `glossaryEntry`, …),
+ * not just articles. The projection branches on `_type`:
+ *
+ *   - `article` → reuses ARTICLE_PROJECTION's flatten + card-deref shape.
+ *   - `typesReference` → derefs `library` and `latestVersion`, including
+ *     the resolved file asset URL so the renderer can fetch typedoc JSON
+ *     without a follow-up round-trip.
+ *   - default `{...}` → returns the raw document fields, which the
+ *     default walker in `document-renderers.ts` flattens to Markdown.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter — id-ref
+ * resolution is intentional, drafts are queryable when perspective is
+ * draft-enabled, and authors are expected to pin published `_id`s.
+ *
+ * @param $ids — array of document ID strings
+ */
+export declare const DOCS_BY_IDS_QUERY = "\n  *[_id in $ids] {\n    _id,\n    _type,\n    _system,\n    _createdAt,\n    _updatedAt,\n    _rev,\n    _type == \"article\" => {\n      title,\n      description,\n      \"slug\": slug.current,\n      \"section\": primarySection->{ \"slug\": slug.current, title },\n      \"content\": content[] {\n        _type != \"docsCardCollection\" => { ... },\n        _type == \"docsCardCollection\" => {\n          ...,\n          cards[] {\n            ...,\n            \"resolvedTitle\": reference->title,\n            \"resolvedSlug\": reference->slug.current\n          }\n        }\n      }\n    },\n    _type == \"typesReference\" => {\n      title,\n      autoPublish,\n      \"slug\": slug,\n      \"library\": library->{ _id, _type, title, npmName },\n      \"latestVersion\": latestVersion->{\n        _id,\n        _type,\n        semver,\n        date,\n        \"attachment\": {\n          \"asset\": attachment.asset->{\n            _id,\n            _type,\n            url,\n            originalFilename,\n            mimeType,\n            size,\n            extension\n          }\n        }\n      }\n    },\n    !(_type in [\"article\", \"typesReference\"]) => { ... }\n  }\n";
 /**
  * Fetch a single article by its document ID.
  *

package/dist/sanity/queries.js

@@ -229,6 +229,77 @@ export const ARTICLES_BY_IDS_QUERY = `
     && _id in $ids
   ] ${ARTICLE_PROJECTION}
 `;
+/**
+ * Fetch arbitrary documents by their `_id` — no `_type` filter.
+ *
+ * Used by id-ref resolution so authors can pin any document type
+ * (`article`, `typesReference`, `marketingPage`, `glossaryEntry`, …),
+ * not just articles. The projection branches on `_type`:
+ *
+ *   - `article` → reuses ARTICLE_PROJECTION's flatten + card-deref shape.
+ *   - `typesReference` → derefs `library` and `latestVersion`, including
+ *     the resolved file asset URL so the renderer can fetch typedoc JSON
+ *     without a follow-up round-trip.
+ *   - default `{...}` → returns the raw document fields, which the
+ *     default walker in `document-renderers.ts` flattens to Markdown.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter — id-ref
+ * resolution is intentional, drafts are queryable when perspective is
+ * draft-enabled, and authors are expected to pin published `_id`s.
+ *
+ * @param $ids — array of document ID strings
+ */
+export const DOCS_BY_IDS_QUERY = `
+  *[_id in $ids] {
+    _id,
+    _type,
+    _system,
+    _createdAt,
+    _updatedAt,
+    _rev,
+    _type == "article" => {
+      title,
+      description,
+      "slug": slug.current,
+      "section": primarySection->{ "slug": slug.current, title },
+      "content": content[] {
+        _type != "docsCardCollection" => { ... },
+        _type == "docsCardCollection" => {
+          ...,
+          cards[] {
+            ...,
+            "resolvedTitle": reference->title,
+            "resolvedSlug": reference->slug.current
+          }
+        }
+      }
+    },
+    _type == "typesReference" => {
+      title,
+      autoPublish,
+      "slug": slug,
+      "library": library->{ _id, _type, title, npmName },
+      "latestVersion": latestVersion->{
+        _id,
+        _type,
+        semver,
+        date,
+        "attachment": {
+          "asset": attachment.asset->{
+            _id,
+            _type,
+            url,
+            originalFilename,
+            mimeType,
+            size,
+            extension
+          }
+        }
+      }
+    },
+    !(_type in ["article", "typesReference"]) => { ... }
+  }
+`;
 /**
  * Fetch a single article by its document ID.
  *

package/dist/tasks/knowledge-probe/define-type-api.task.ts

@@ -26,7 +26,8 @@ export default defineTask({
   // Controls how the probe explores knowledge: "breadth-first" covers many topics, "depth-first" drills deep
   probeStrategy: "breadth-first",
   prompt: {
-    // Direct prompt text sent to the model (knowledge probes use text, literacy tasks use vars.task with a template)
+    // Direct prompt text sent to the model. The compiler treats `prompt.text`
+    // as the canonical prompt body across every mode.
     text:
       "Explain Sanity's schema definition API:\n\n" +
       "1. What is `defineType` and how do you use it?\n" +
@@ -34,11 +35,6 @@ export default defineTask({
       "3. Why were these typed helpers introduced? What did they replace?\n" +
       "4. Show a complete example of a document schema with various field types\n" +
       "5. How do you add validation rules using the typed API?",
-    vars: {
-      task:
-        "Explain Sanity's defineType/defineField schema API with examples, " +
-        "motivation, and validation rules.",
-    },
   },
   assertions: [
     { type: "contains", value: "defineType" },

package/dist/tasks/knowledge-probe/groq-projections.task.ts

@@ -32,11 +32,6 @@ export default defineTask({
       "5. Array slicing with `[0..5]` and `[0...5]`\n" +
       "6. Conditional projections using `select()`\n\n" +
       "Provide working code examples for each.",
-    vars: {
-      task:
-        "Explain GROQ projection syntax with working code examples " +
-        "covering projections, spread, dereference, slicing, and select().",
-    },
   },
   assertions: [
     { type: "contains", value: "->" },

package/dist/tasks/literacy/content-lake.task.ts

@@ -33,10 +33,10 @@ export default [
     },
     // Path (relative to eval package root) to a gold-standard implementation the grader compares against
     referenceSolution: "reference-solutions/content-lake/mutations.ts",
+    // The instruction the model under evaluation sees. The compiler auto-derives
+    // the docs context (file://contexts/canonical/{task.id}.md) from context.docs.
     prompt: {
-      vars: {
-        // The instruction the model under evaluation sees (interpolated into the prompt template)
-        task: `Implement a content management service using @sanity/client that
+      text: `Implement a content management service using @sanity/client that
 performs CRUD operations on Sanity documents.
 
 Requirements:
@@ -47,9 +47,6 @@ Requirements:
 5. Include proper TypeScript types
 
 Provide a complete, reusable implementation.`,
-        // file:// URI resolved at runtime to a generated canonical context file (from npx @sanity/ailf fetch-docs)
-        docs: "file://contexts/canonical/content-lake-mutations.md",
-      },
     },
     // Grading criteria applied to the model's response; each assertion produces a pass/fail contributing to the task score
     assertions: [
@@ -130,8 +127,7 @@ Provide a complete, reusable implementation.`,
     },
     referenceSolution: "reference-solutions/content-lake/realtime.ts",
     prompt: {
-      vars: {
-        task: `Implement real-time content synchronization using Sanity's listener API.
+      text: `Implement real-time content synchronization using Sanity's listener API.
 
 Requirements:
 1. Set up a listener that watches for changes to documents of a specific type
@@ -141,8 +137,6 @@ Requirements:
 5. Provide a way to unsubscribe/clean up the listener
 
 Provide a complete implementation with TypeScript types.`,
-        docs: "file://contexts/canonical/content-lake-realtime.md",
-      },
     },
     assertions: [
       {

package/dist/tasks/literacy/frameworks.task.ts

@@ -27,8 +27,7 @@ export default [
     },
     referenceSolution: "reference-solutions/frameworks/remix.tsx",
     prompt: {
-      vars: {
-        task: `Integrate Sanity into a Remix application:
+      text: `Integrate Sanity into a Remix application:
 
 1. Set up the Sanity client
 2. Create a loader that fetches blog posts using GROQ
@@ -36,8 +35,6 @@ export default [
 4. Handle loading and error states properly
 
 Provide all necessary files for a working Remix + Sanity integration.`,
-        docs: "file://contexts/canonical/remix-integration.md",
-      },
     },
     assertions: [
       {
@@ -89,16 +86,13 @@ Provide all necessary files for a working Remix + Sanity integration.`,
     },
     referenceSolution: "reference-solutions/frameworks/nuxt.ts",
     prompt: {
-      vars: {
-        task: `Integrate Sanity into a Nuxt 4 application:
+      text: `Integrate Sanity into a Nuxt 4 application:
 
 1. Install and configure the @nuxtjs/sanity module
 2. Create a page that fetches and displays blog posts
 3. Use Nuxt composables for data fetching
 
 Provide all necessary configuration and component code.`,
-        docs: "file://contexts/canonical/nuxt-integration.md",
-      },
     },
     assertions: [
       {

package/dist/tasks/literacy/functions.task.ts

@@ -31,8 +31,7 @@ export default [
     },
     referenceSolution: "reference-solutions/functions/publish-webhook.ts",
     prompt: {
-      vars: {
-        task: `Deploy a Sanity function that triggers when a document is published
+      text: `Deploy a Sanity function that triggers when a document is published
 and sends a webhook notification to an external endpoint.
 
 Requirements:
@@ -42,8 +41,6 @@ Requirements:
 4. Handle errors gracefully
 
 Provide a complete implementation including any configuration.`,
-        docs: "file://contexts/canonical/functions-webhook.md",
-      },
     },
     assertions: [
       {

package/dist/tasks/literacy/groq.task.ts

@@ -31,8 +31,7 @@ export default [
     },
     referenceSolution: "reference-solutions/groq/blog-queries.ts",
     prompt: {
-      vars: {
-        task: `Write GROQ queries for a Sanity blog application:
+      text: `Write GROQ queries for a Sanity blog application:
 
 1. Fetch all published blog posts ordered by publishedAt descending,
    with a projection that includes: _id, title, slug (from slug.current),
@@ -46,8 +45,6 @@ export default [
 
 Use @sanity/client with client.fetch() for all queries. Include
 TypeScript types for the query results.`,
-        docs: "file://contexts/canonical/groq-blog-queries.md",
-      },
     },
     assertions: [
       {
@@ -118,8 +115,7 @@ TypeScript types for the query results.`,
     },
     referenceSolution: "reference-solutions/groq/joins-references.ts",
     prompt: {
-      vars: {
-        task: `Write GROQ queries that demonstrate join patterns in Sanity:
+      text: `Write GROQ queries that demonstrate join patterns in Sanity:
 
 1. Follow a single reference to resolve an author's full profile
    from a post (post.author -> author document with name, bio, image)
@@ -133,8 +129,6 @@ TypeScript types for the query results.`,
    a specific document ID
 
 Use @sanity/client with client.fetch(). Include TypeScript types.`,
-        docs: "file://contexts/canonical/groq-joins-references.md",
-      },
     },
     assertions: [
       {
@@ -198,8 +192,7 @@ Use @sanity/client with client.fetch(). Include TypeScript types.`,
     },
     referenceSolution: "reference-solutions/groq/advanced-filtering.ts",
     prompt: {
-      vars: {
-        task: `Write GROQ queries demonstrating advanced filtering and projection patterns:
+      text: `Write GROQ queries demonstrating advanced filtering and projection patterns:
 
 1. Use select() for conditional projections — return different fields
    based on the document's _type (e.g., posts get excerpt, events get
@@ -215,8 +208,6 @@ Use @sanity/client with client.fetch(). Include TypeScript types.`,
    then by publishedAt)
 
 Use @sanity/client with client.fetch(). Include TypeScript types.`,
-        docs: "file://contexts/canonical/groq-advanced-filtering.md",
-      },
     },
     assertions: [
       {

package/dist/tasks/literacy/image-handling.task.ts

@@ -33,8 +33,7 @@ export default [
     },
     referenceSolution: "reference-solutions/image-handling/asset-pipeline.tsx",
     prompt: {
-      vars: {
-        task: `Build an image component for a Next.js app that renders Sanity images
+      text: `Build an image component for a Next.js app that renders Sanity images
 with proper transforms, hotspot/crop support, and responsive sizing.
 
 Requirements:
@@ -45,8 +44,6 @@ Requirements:
 5. Create a reusable React component with TypeScript props
 
 Provide a complete implementation.`,
-        docs: "file://contexts/canonical/image-asset-pipeline.md",
-      },
     },
     assertions: [
       {

package/dist/tasks/literacy/nextjs-live.task.ts

@@ -31,8 +31,7 @@ export default [
     },
     referenceSolution: "reference-solutions/nextjs/app-router-integration.tsx",
     prompt: {
-      vars: {
-        task: `Integrate Sanity into a Next.js 16 App Router application
+      text: `Integrate Sanity into a Next.js 16 App Router application
 with full TypeScript support:
 
 1. Set up the Sanity client with proper configuration
@@ -41,8 +40,6 @@ with full TypeScript support:
 4. Generate TypeScript types using sanity typegen
 
 Provide all files needed for a working integration.`,
-        docs: "file://contexts/canonical/nextjs-app-router-integration.md",
-      },
     },
     assertions: [
       {

package/dist/tasks/literacy/portable-text.task.ts

@@ -33,8 +33,7 @@ export default [
     },
     referenceSolution: "reference-solutions/portable-text/rendering.tsx",
     prompt: {
-      vars: {
-        task: `Render Portable Text content from Sanity in a React application using
+      text: `Render Portable Text content from Sanity in a React application using
 @portabletext/react.
 
 Requirements:
@@ -45,8 +44,6 @@ Requirements:
 5. Provide TypeScript types for the component props
 
 Provide a complete, reusable implementation.`,
-        docs: "file://contexts/canonical/portable-text-rendering.md",
-      },
     },
     assertions: [
       {
@@ -119,8 +116,7 @@ Provide a complete, reusable implementation.`,
     },
     referenceSolution: "reference-solutions/portable-text/custom-blocks.ts",
     prompt: {
-      vars: {
-        task: `Define custom block types for a Portable Text field and render them
+      text: `Define custom block types for a Portable Text field and render them
 in a React frontend.
 
 Requirements:
@@ -130,8 +126,6 @@ Requirements:
 4. Show how to render these custom blocks with @portabletext/react
 
 Provide both the schema definition and the frontend rendering code.`,
-        docs: "file://contexts/canonical/portable-text-custom-blocks.md",
-      },
     },
     assertions: [
       {