@sanity/ailf 0.1.0

package/dist/sanity/queries.d.ts

@@ -0,0 +1,133 @@
+/**
+ * GROQ queries scoped to each documentation feature area.
+ *
+ * Schema notes (dataset: gabe-wyatt-doc-plat-dev-2026-01-05):
+ *
+ *   _type == "article"        — 614 documentation articles
+ *   primarySection             — reference to a docsNavSection
+ *   content[]                  — Portable Text rich-text field
+ *   slug.current               — URL slug
+ *
+ *   Code blocks in `content`:
+ *     _type == "codeBlock" → blocks[].code.code, blocks[].code.language, blocks[].filename
+ *
+ *   Sections are _type == "docsNavSection" with slug.current.
+ *
+ * Each query joins through primarySection._ref to the relevant
+ * docsNavSection IDs and returns a consistent projection.
+ */
+export declare const FEATURE_AREA_QUERIES: {
+    /**
+     * Other Frameworks — Nuxt, React Router/Remix, Astro
+     */
+    readonly frameworks: "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref in [\n          \"b2c937d0-34b3-435e-818b-d0c8520ea9b8\",\n          \"e223241c-e207-41e0-8e12-f80e78203cf1\",\n          \"73bebb61-e508-42b7-b44b-c4703ae42d01\"\n        ]\n        || (primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n            && (title match \"Remix*\" || title match \"Nuxt*\"\n                || title match \"Astro*\" || title match \"SvelteKit*\"))\n      )\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  ";
+    /**
+     * Functions / Compute / AI — serverless functions, webhooks
+     * Section: "Compute and AI" (12 articles)
+     */
+    readonly functions: "\n    *[_type == \"article\"\n      && primarySection._ref == \"3024ce79-c196-49ee-a237-a327d6a6348f\"\n      && !(_id in path(\"drafts.**\"))\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  ";
+    /**
+     * GROQ Query Language — introduction, syntax, joins, filtering, projections
+     * Combines: Content Lake section GROQ articles + Developer Guides articles
+     * about querying + title-matched GROQ articles across all sections.
+     */
+    readonly groq: "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref == \"60a6bcb5-9706-4cab-9153-57725e28f4d0\"\n        || primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n      )\n      && (\n        title match \"GROQ*\"\n        || title match \"*GROQ*\"\n        || title match \"Query*\"\n        || title match \"How Queries*\"\n        || slug.current match \"groq-*\"\n        || slug.current match \"query-*\"\n        || slug.current match \"how-queries-*\"\n        || slug.current match \"paginating-with-groq\"\n        || slug.current match \"high-performance-groq\"\n      )\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  ";
+    /**
+     * Next.js integration + Live Content API
+     * Combines: Next.js quickstart section + developer-guide articles
+     * mentioning Next.js or Live Content.
+     */
+    readonly "nextjs-live": "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref == \"6208dff1-bba7-487a-a6bb-a0ffccb5846c\"\n        || (primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n            && (title match \"Next*\" || title match \"*Live*\"))\n      )\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  ";
+    /**
+     * Studio Setup & Customization
+     * Section: "Studio" (116 articles)
+     */
+    readonly "studio-setup": "\n    *[_type == \"article\"\n      && primarySection._ref == \"d67e3879-0342-4a80-8a2d-e35908df35cc\"\n      && !(_id in path(\"drafts.**\"))\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  ";
+    /**
+     * Visual Editing — Presentation tool, overlays, live preview
+     * Section: "Visual Editing" (24 articles)
+     */
+    readonly "visual-editing": "\n    *[_type == \"article\"\n      && primarySection._ref == \"4e0ef463-01e2-48db-9a31-38b3912ececd\"\n      && !(_id in path(\"drafts.**\"))\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  ";
+};
+export type FeatureArea = keyof typeof FEATURE_AREA_QUERIES;
+export declare const ALL_FEATURE_AREAS: FeatureArea[];
+/**
+ * Fetch a single article by its slug.
+ * Returns the same projection shape as the feature-area queries.
+ */
+export declare const ARTICLE_BY_SLUG_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n    && !(_id in path(\"drafts.**\"))\n  ][0] {\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 all published articles (for full-corpus generation).
+ */
+export declare const ALL_ARTICLES_QUERY = "\n  *[_type == \"article\"\n    && !(_id in path(\"drafts.**\"))\n  ] | order(primarySection->slug.current, title) {\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 article metadata for a list of slugs.
+ *
+ * Returns lightweight metadata (slug + _rev) for comparison between
+ * published and perspective states. The _rev field changes when a document
+ * is modified, making it an efficient diff signal.
+ *
+ * Usage: client.fetch(ARTICLES_METADATA_BY_SLUGS_QUERY, { slugs: ["slug-a", "slug-b"] })
+ */
+export declare const ARTICLES_METADATA_BY_SLUGS_QUERY = "\n  *[_type == \"article\"\n    && slug.current in $slugs\n    && !(_id in path(\"drafts.**\"))\n  ] {\n    \"slug\": slug.current,\n    _id,\n    _rev,\n    title\n  }\n";
+/**
+ * Fetch a single article by its slug — identical to ARTICLE_BY_SLUG_QUERY
+ * but designed to be called with a perspective-enabled client.
+ *
+ * Returns the full article projection for content comparison.
+ */
+export declare const ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n  ][0] {\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 articles by their document IDs.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter because this
+ * query is designed for use with perspective-enabled clients where draft
+ * filtering is handled at the client level.
+ *
+ * @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 a single article by its document ID.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter because this
+ * query is designed for use with perspective-enabled clients where draft
+ * filtering is handled at the client level.
+ *
+ * @param $id — document ID string
+ */
+export declare const ARTICLE_BY_ID_QUERY = "\n  *[_type == \"article\"\n    && _id == $id\n  ][0] {\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";
+/**
+ * Resolve an article slug from a URL path segment.
+ *
+ * Handles simple paths (just the slug, e.g., "webhooks") by matching
+ * against slug.current. Returns the slug for downstream slug-based fetching.
+ *
+ * @param $slug — the path segment (article slug)
+ */
+export declare const ARTICLE_SLUG_BY_PATH_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n    && !(_id in path(\"drafts.**\"))\n  ][0] { \"slug\": slug.current, \"sectionSlug\": primarySection->slug.current }\n";
+/**
+ * Resolve an article slug from a section-qualified path.
+ *
+ * Handles compound paths like "content-lake/webhooks" where the first
+ * segment is the section slug and the last segment is the article slug.
+ * This disambiguates articles that share a slug across different sections.
+ *
+ * @param $articleSlug — the article slug (last path segment)
+ * @param $sectionSlug — the section slug (first path segment)
+ */
+export declare const ARTICLE_SLUG_BY_SECTION_PATH_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $articleSlug\n    && primarySection->slug.current == $sectionSlug\n    && !(_id in path(\"drafts.**\"))\n  ][0] { \"slug\": slug.current }\n";
+/**
+ * Find all article documents that are versioned within a content release.
+ *
+ * Uses `sanity::partOfRelease()` to identify documents that have versions
+ * in the specified release. Must be called with a perspective-enabled
+ * client so the versioned content is visible.
+ *
+ * Returns the original document IDs (not the `versions.*` prefixed ones)
+ * because the perspective client transparently resolves versioned docs
+ * back to their canonical shape.
+ *
+ * @param $releaseId — the release ID (e.g., "ailf-scenario-01-test")
+ */
+export declare const ARTICLES_IN_RELEASE_QUERY = "\n  *[_type == \"article\"\n    && sanity::partOfRelease($releaseId)\n  ] { \"slug\": slug.current, _id, title }\n";

package/dist/sanity/queries.js

@@ -0,0 +1,300 @@
+/**
+ * GROQ queries scoped to each documentation feature area.
+ *
+ * Schema notes (dataset: gabe-wyatt-doc-plat-dev-2026-01-05):
+ *
+ *   _type == "article"        — 614 documentation articles
+ *   primarySection             — reference to a docsNavSection
+ *   content[]                  — Portable Text rich-text field
+ *   slug.current               — URL slug
+ *
+ *   Code blocks in `content`:
+ *     _type == "codeBlock" → blocks[].code.code, blocks[].code.language, blocks[].filename
+ *
+ *   Sections are _type == "docsNavSection" with slug.current.
+ *
+ * Each query joins through primarySection._ref to the relevant
+ * docsNavSection IDs and returns a consistent projection.
+ */
+// ---------------------------------------------------------------------------
+// Section IDs (docsNavSection._id values)
+// ---------------------------------------------------------------------------
+const SECTION_IDS = {
+    apisAndSdks: "bc30def4-a95a-44ef-a4d4-cacb4d55e816",
+    appSdk: "d01fba8e-da8d-40ba-a09f-1a5f000de4a4",
+    astroQuickstart: "73bebb61-e508-42b7-b44b-c4703ae42d01",
+    computeAndAi: "3024ce79-c196-49ee-a237-a327d6a6348f",
+    contentLake: "60a6bcb5-9706-4cab-9153-57725e28f4d0",
+    developerGuides: "ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb",
+    gettingStarted: "f78cfeb7-ebc4-4684-b7fa-99c7ae528e68",
+    libraries: "4551373a-8764-4da3-ac65-406d7dfb96e2",
+    nextJsQuickstart: "6208dff1-bba7-487a-a6bb-a0ffccb5846c",
+    nuxtJsQuickstart: "b2c937d0-34b3-435e-818b-d0c8520ea9b8",
+    reactRouterQuickstart: "e223241c-e207-41e0-8e12-f80e78203cf1",
+    studio: "d67e3879-0342-4a80-8a2d-e35908df35cc",
+    visualEditing: "4e0ef463-01e2-48db-9a31-38b3912ececd",
+};
+// ---------------------------------------------------------------------------
+// Shared projection
+// ---------------------------------------------------------------------------
+/**
+ * Standard projection applied to every article query.
+ *
+ * Returns the raw Portable Text `content` array so that the Node-side
+ * converter (@portabletext/markdown) can produce well-structured Markdown
+ * with headings, code fences, tables, callouts, etc.
+ */
+const ARTICLE_PROJECTION = `{
+  title,
+  description,
+  "slug": slug.current,
+  "section": primarySection->{ "slug": slug.current, title },
+  "content": content[] {
+    // Pass through all standard blocks unchanged
+    _type != "docsCardCollection" => { ... },
+    // Resolve references inside card collections so we get titles/slugs
+    _type == "docsCardCollection" => {
+      ...,
+      cards[] {
+        ...,
+        "resolvedTitle": reference->title,
+        "resolvedSlug": reference->slug.current
+      }
+    }
+  }
+}`;
+// ---------------------------------------------------------------------------
+// Feature-area queries
+// ---------------------------------------------------------------------------
+export const FEATURE_AREA_QUERIES = {
+    /**
+     * Other Frameworks — Nuxt, React Router/Remix, Astro
+     */
+    frameworks: `
+    *[_type == "article"
+      && !(_id in path("drafts.**"))
+      && (
+        primarySection._ref in [
+          "${SECTION_IDS.nuxtJsQuickstart}",
+          "${SECTION_IDS.reactRouterQuickstart}",
+          "${SECTION_IDS.astroQuickstart}"
+        ]
+        || (primarySection._ref == "${SECTION_IDS.developerGuides}"
+            && (title match "Remix*" || title match "Nuxt*"
+                || title match "Astro*" || title match "SvelteKit*"))
+      )
+    ] ${ARTICLE_PROJECTION}
+  `,
+    /**
+     * Functions / Compute / AI — serverless functions, webhooks
+     * Section: "Compute and AI" (12 articles)
+     */
+    functions: `
+    *[_type == "article"
+      && primarySection._ref == "${SECTION_IDS.computeAndAi}"
+      && !(_id in path("drafts.**"))
+    ] ${ARTICLE_PROJECTION}
+  `,
+    /**
+     * GROQ Query Language — introduction, syntax, joins, filtering, projections
+     * Combines: Content Lake section GROQ articles + Developer Guides articles
+     * about querying + title-matched GROQ articles across all sections.
+     */
+    groq: `
+    *[_type == "article"
+      && !(_id in path("drafts.**"))
+      && (
+        primarySection._ref == "${SECTION_IDS.contentLake}"
+        || primarySection._ref == "${SECTION_IDS.developerGuides}"
+      )
+      && (
+        title match "GROQ*"
+        || title match "*GROQ*"
+        || title match "Query*"
+        || title match "How Queries*"
+        || slug.current match "groq-*"
+        || slug.current match "query-*"
+        || slug.current match "how-queries-*"
+        || slug.current match "paginating-with-groq"
+        || slug.current match "high-performance-groq"
+      )
+    ] ${ARTICLE_PROJECTION}
+  `,
+    /**
+     * Next.js integration + Live Content API
+     * Combines: Next.js quickstart section + developer-guide articles
+     * mentioning Next.js or Live Content.
+     */
+    "nextjs-live": `
+    *[_type == "article"
+      && !(_id in path("drafts.**"))
+      && (
+        primarySection._ref == "${SECTION_IDS.nextJsQuickstart}"
+        || (primarySection._ref == "${SECTION_IDS.developerGuides}"
+            && (title match "Next*" || title match "*Live*"))
+      )
+    ] ${ARTICLE_PROJECTION}
+  `,
+    /**
+     * Studio Setup & Customization
+     * Section: "Studio" (116 articles)
+     */
+    "studio-setup": `
+    *[_type == "article"
+      && primarySection._ref == "${SECTION_IDS.studio}"
+      && !(_id in path("drafts.**"))
+    ] ${ARTICLE_PROJECTION}
+  `,
+    /**
+     * Visual Editing — Presentation tool, overlays, live preview
+     * Section: "Visual Editing" (24 articles)
+     */
+    "visual-editing": `
+    *[_type == "article"
+      && primarySection._ref == "${SECTION_IDS.visualEditing}"
+      && !(_id in path("drafts.**"))
+    ] ${ARTICLE_PROJECTION}
+  `,
+};
+export const ALL_FEATURE_AREAS = Object.keys(FEATURE_AREA_QUERIES);
+// ---------------------------------------------------------------------------
+// Single-article query (used by canonical doc fetcher)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch a single article by its slug.
+ * Returns the same projection shape as the feature-area queries.
+ */
+export const ARTICLE_BY_SLUG_QUERY = `
+  *[_type == "article"
+    && slug.current == $slug
+    && !(_id in path("drafts.**"))
+  ][0] ${ARTICLE_PROJECTION}
+`;
+/**
+ * Fetch all published articles (for full-corpus generation).
+ */
+export const ALL_ARTICLES_QUERY = `
+  *[_type == "article"
+    && !(_id in path("drafts.**"))
+  ] | order(primarySection->slug.current, title) ${ARTICLE_PROJECTION}
+`;
+// ---------------------------------------------------------------------------
+// Perspective diffing queries
+// ---------------------------------------------------------------------------
+/**
+ * Fetch article metadata for a list of slugs.
+ *
+ * Returns lightweight metadata (slug + _rev) for comparison between
+ * published and perspective states. The _rev field changes when a document
+ * is modified, making it an efficient diff signal.
+ *
+ * Usage: client.fetch(ARTICLES_METADATA_BY_SLUGS_QUERY, { slugs: ["slug-a", "slug-b"] })
+ */
+export const ARTICLES_METADATA_BY_SLUGS_QUERY = `
+  *[_type == "article"
+    && slug.current in $slugs
+    && !(_id in path("drafts.**"))
+  ] {
+    "slug": slug.current,
+    _id,
+    _rev,
+    title
+  }
+`;
+/**
+ * Fetch a single article by its slug — identical to ARTICLE_BY_SLUG_QUERY
+ * but designed to be called with a perspective-enabled client.
+ *
+ * Returns the full article projection for content comparison.
+ */
+export const ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY = `
+  *[_type == "article"
+    && slug.current == $slug
+  ][0] ${ARTICLE_PROJECTION}
+`;
+// ---------------------------------------------------------------------------
+// Document ID queries
+// ---------------------------------------------------------------------------
+/**
+ * Fetch articles by their document IDs.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter because this
+ * query is designed for use with perspective-enabled clients where draft
+ * filtering is handled at the client level.
+ *
+ * @param $ids — array of document ID strings
+ */
+export const ARTICLES_BY_IDS_QUERY = `
+  *[_type == "article"
+    && _id in $ids
+  ] ${ARTICLE_PROJECTION}
+`;
+/**
+ * Fetch a single article by its document ID.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter because this
+ * query is designed for use with perspective-enabled clients where draft
+ * filtering is handled at the client level.
+ *
+ * @param $id — document ID string
+ */
+export const ARTICLE_BY_ID_QUERY = `
+  *[_type == "article"
+    && _id == $id
+  ][0] ${ARTICLE_PROJECTION}
+`;
+// ---------------------------------------------------------------------------
+// Path-based resolution queries
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an article slug from a URL path segment.
+ *
+ * Handles simple paths (just the slug, e.g., "webhooks") by matching
+ * against slug.current. Returns the slug for downstream slug-based fetching.
+ *
+ * @param $slug — the path segment (article slug)
+ */
+export const ARTICLE_SLUG_BY_PATH_QUERY = `
+  *[_type == "article"
+    && slug.current == $slug
+    && !(_id in path("drafts.**"))
+  ][0] { "slug": slug.current, "sectionSlug": primarySection->slug.current }
+`;
+/**
+ * Resolve an article slug from a section-qualified path.
+ *
+ * Handles compound paths like "content-lake/webhooks" where the first
+ * segment is the section slug and the last segment is the article slug.
+ * This disambiguates articles that share a slug across different sections.
+ *
+ * @param $articleSlug — the article slug (last path segment)
+ * @param $sectionSlug — the section slug (first path segment)
+ */
+export const ARTICLE_SLUG_BY_SECTION_PATH_QUERY = `
+  *[_type == "article"
+    && slug.current == $articleSlug
+    && primarySection->slug.current == $sectionSlug
+    && !(_id in path("drafts.**"))
+  ][0] { "slug": slug.current }
+`;
+// ---------------------------------------------------------------------------
+// Content Release — perspective ref expansion
+// ---------------------------------------------------------------------------
+/**
+ * Find all article documents that are versioned within a content release.
+ *
+ * Uses `sanity::partOfRelease()` to identify documents that have versions
+ * in the specified release. Must be called with a perspective-enabled
+ * client so the versioned content is visible.
+ *
+ * Returns the original document IDs (not the `versions.*` prefixed ones)
+ * because the perspective client transparently resolves versioned docs
+ * back to their canonical shape.
+ *
+ * @param $releaseId — the release ID (e.g., "ailf-scenario-01-test")
+ */
+export const ARTICLES_IN_RELEASE_QUERY = `
+  *[_type == "article"
+    && sanity::partOfRelease($releaseId)
+  ] { "slug": slug.current, _id, title }
+`;

package/dist/schedules/digest.d.ts

@@ -0,0 +1,116 @@
+/**
+ * schedules/digest.ts
+ *
+ * Weekly digest engine — aggregates evaluation reports from a time window
+ * and computes trend summaries for notification delivery.
+ *
+ * The digest answers: "How did our AI literacy scores trend this week?"
+ *
+ * Data flow:
+ * 1. Query Sanity for all reports in the lookback window
+ * 2. Group by feature area
+ * 3. Compute trend direction and magnitude per area
+ * 4. Identify regressions, improvements, and stable areas
+ * 5. Return a structured DigestSummary for formatting
+ *
+ * @see docs/design-docs/report-store/notifications.md
+ * @see docs/design-docs/report-store/implementation.md — Phase 5
+ */
+import type { SanityClient } from "@sanity/client";
+/** Trend analysis for a single feature area */
+export interface AreaTrend {
+    /** Feature area name */
+    area: string;
+    /** Score at the start of the window */
+    firstScore: number;
+    /** Score at the end of the window */
+    lastScore: number;
+    /** Number of data points in the window */
+    reportCount: number;
+    /** Net score change (last - first) */
+    scoreDelta: number;
+    /** Trend direction */
+    trend: TrendDirection;
+}
+/** A single report data point from the lookback window */
+export interface DigestReportEntry {
+    /** ISO timestamp */
+    completedAt: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Evaluation mode */
+    mode: string;
+    /** Overall average score */
+    overallScore: number;
+    /** Report ID */
+    reportId: string;
+    /** Per-area scores */
+    scores: {
+        feature: string;
+        totalScore: number;
+    }[];
+    /** Documentation source name */
+    sourceName: string;
+    /** Report tag (schedule name) */
+    tag?: string;
+}
+/** The complete digest summary */
+export interface DigestSummary {
+    /** Per-area trend breakdown */
+    areaTrends: AreaTrend[];
+    /** Areas that improved by more than the noise threshold */
+    improved: string[];
+    /** End of the lookback window (usually "now") */
+    lookbackEnd: string;
+    /** Start of the lookback window */
+    lookbackStart: string;
+    /** Overall score delta across the window */
+    overallDelta: number;
+    /** Overall score at the end of the window */
+    overallLatest: number;
+    /** Overall trend direction */
+    overallTrend: TrendDirection;
+    /** Areas that regressed by more than the noise threshold */
+    regressed: string[];
+    /** Total number of reports in the window */
+    reportCount: number;
+    /** Areas with score changes within the noise threshold */
+    stable: string[];
+    /** Total evaluation cost in the window (if available) */
+    totalCost?: number;
+}
+/** Trend direction for a feature area or overall score */
+export type TrendDirection = "improving" | "regressing" | "stable";
+export interface DigestOptions {
+    /** Override the Sanity client (for testing) */
+    client?: SanityClient;
+    /** Sanity dataset for report queries (independent of eval dataset) */
+    dataset?: string;
+    /** How many days to look back (default: 7) */
+    lookbackDays?: number;
+    /** Noise threshold for trend classification (default: 2) */
+    noiseThreshold?: number;
+    /** Sanity project ID for report queries (independent of eval project) */
+    projectId?: string;
+    /** Sanity API token */
+    token?: string;
+}
+/**
+ * Build a digest summary from a chronologically-ordered list of reports.
+ *
+ * Pure function — no I/O, fully testable.
+ */
+export declare function buildDigestSummary(reports: DigestReportEntry[], lookbackStart: Date, lookbackEnd: Date, noiseThreshold?: number): DigestSummary;
+/**
+ * Classify a score delta into a trend direction.
+ */
+export declare function classifyTrend(delta: number, threshold?: number): TrendDirection;
+/**
+ * Generate a digest summary from recent evaluation reports.
+ *
+ * Queries the Sanity Content Lake for all reports within the lookback
+ * window and computes trend analysis per area.
+ *
+ * @returns DigestSummary, or null if no reports found or on error
+ */
+export declare function generateDigest(options?: DigestOptions): Promise<DigestSummary | null>;