@farming-labs/docs 0.2.57 → 0.2.58

package/dist/{types-R-DN23yw.d.mts → types-C1nPRXqo.d.mts}

@@ -1342,6 +1342,8 @@ interface DocsSearchAdapterContext {
   locale?: string;
   pathname?: string;
   siteTitle?: string;
+  /** Optional cancellation signal, including diagnostic timeouts. */
+  signal?: AbortSignal;
 }
 interface DocsSearchAdapter {
   name: string;
@@ -2380,7 +2382,28 @@ interface DocsAgentGoldenTaskExpectation {
   examples?: DocsAgentGoldenExpectedExample[];
   /** Minimum share of context bytes that must come from relevant sources. */
   minUsefulByteRatio?: number;
+  /**
+   * Scope that the returned sources must actually select. Unlike `filters`, this is an
+   * assertion and does not constrain retrieval, so it can detect a wrong framework,
+   * version, or locale result.
+   */
+  scope?: DocsAgentGoldenTaskFilters;
+  /** Assertions evaluated against an explicitly configured answer runner. */
+  answer?: DocsAgentGoldenAnswerExpectation;
+}
+interface DocsAgentGoldenAnswerExpectation {
+  /** Literal fragments that must occur in the generated answer. */
+  includes?: string[];
+  /** Literal fragments that must not occur in the generated answer. */
+  excludes?: string[];
+  /** Citations that the generated answer must contain. */
+  requiredCitations?: string[];
+  /** Additional answer citations that are valid but not required. */
+  allowedCitations?: string[];
+  /** Citations that the generated answer must not contain. */
+  forbiddenCitations?: string[];
 }
+type DocsAgentGoldenExampleVerification = "present" | "syntax" | "execute";
 interface DocsAgentGoldenExpectedExample {
   /** Canonical page or section URL containing the example. */
   source?: string;
@@ -2392,7 +2415,13 @@ interface DocsAgentGoldenExpectedExample {
   runnable?: boolean;
   /** Literal fragments that must occur in the example. */
   includes?: string[];
+  /**
+   * Verification strength. Runnable examples default to `syntax`; explicitly
+   * non-runnable examples default to `present`. Runtime execution is always opt-in.
+   */
+  verification?: DocsAgentGoldenExampleVerification;
 }
+type DocsAgentEvaluationSurface = "mcp-context" | "configured-search" | "ask-ai-context";
 interface DocsAgentGoldenTask {
   /** Stable identifier shown in doctor/review reports. */
   id: string;
@@ -2404,17 +2433,71 @@ interface DocsAgentGoldenTask {
   tokenBudget?: number;
   /** Number of ranked search results to evaluate. */
   topK?: number;
-  /** Deterministic expectations used to score the task. */
+  /** Override the evaluation surface configured for the task suite. */
+  surface?: DocsAgentEvaluationSurface;
+  /** Evaluator-only expectations used to score the task. */
   expect: DocsAgentGoldenTaskExpectation;
 }
+interface DocsAgentEvaluationSourceReference {
+  url: string;
+  title?: string;
+  framework?: string;
+  version?: string;
+  locale?: string;
+}
+/** Blind task input sent to answer providers. Golden expectations stay evaluator-only. */
+interface DocsAgentEvaluationTaskInput {
+  id: string;
+  query: string;
+  filters?: DocsAgentGoldenTaskFilters;
+}
+/** Serializable, expectation-blind request sent to every configured answer provider. */
+interface DocsAgentEvaluationAnswerRequest {
+  task: DocsAgentEvaluationTaskInput;
+  surface: DocsAgentEvaluationSurface;
+  context: string;
+  sources: readonly DocsAgentEvaluationSourceReference[];
+}
+/** Callback answer input. The abort signal is not serialized for HTTP providers. */
+interface DocsAgentEvaluationAnswerInput extends DocsAgentEvaluationAnswerRequest {
+  /** Aborted when the configured answer timeout elapses. */
+  signal: AbortSignal;
+}
+interface DocsAgentEvaluationAnswerResult {
+  text: string;
+  /** Canonical URLs cited by the answer. Markdown links are also extracted from `text`. */
+  citations?: string[];
+}
+type DocsAgentEvaluationAnswerRunner = (input: DocsAgentEvaluationAnswerInput) => DocsAgentEvaluationAnswerResult | Promise<DocsAgentEvaluationAnswerResult>;
+type DocsAgentEvaluationAnswerProvider = {
+  provider: "callback";
+  run: DocsAgentEvaluationAnswerRunner; /** Abort the callback after this many milliseconds. @default 30000 */
+  timeoutMs?: number;
+} | {
+  provider: "http"; /** Endpoint that accepts `DocsAgentEvaluationAnswerRequest` JSON and returns an answer result. */
+  endpoint: string; /** Optional request headers. Values are never included in evaluation reports. */
+  headers?: Record<string, string>; /** Abort the request after this many milliseconds. @default 30000 */
+  timeoutMs?: number;
+};
 interface DocsAgentEvaluationsConfig {
-  /** Enable deterministic golden-task evaluation. */
+  /** Enable golden-task evaluation. */
   enabled?: boolean;
   /** Default conservative context budget for tasks that omit `tokenBudget`. */
   tokenBudget?: number;
   /** Default retrieval depth for tasks that omit `topK`. */
   topK?: number;
-  /** Golden tasks evaluated offline by `docs doctor` and `docs review`. */
+  /** Retrieval/context surface measured by the task suite. @default "mcp-context" */
+  surface?: DocsAgentEvaluationSurface;
+  /**
+   * Permit configured external search, HTTP answers, and explicit executable-example
+   * verification. Disabled by default so doctor/review remain offline unless explicitly opted in.
+   */
+  allowNetwork?: boolean;
+  /** Timeout for configured retrieval during each task. @default 30000 */
+  searchTimeoutMs?: number;
+  /** Optional callback or HTTP runner used to measure actual generated answers. */
+  answer?: DocsAgentEvaluationAnswerProvider;
+  /** Golden tasks evaluated by `docs doctor` and `docs review`. */
   tasks?: DocsAgentGoldenTask[];
 }
 interface DocsAgentConfig {
@@ -2423,7 +2506,8 @@ interface DocsAgentConfig {
    */
   compact?: DocsAgentCompactConfig;
   /**
-   * Deterministic retrieval, citation, version, example, and token-budget evaluations.
+   * Offline-by-default retrieval, citation, version, example, and token-budget evaluations.
+   * External providers and runtime execution require explicit opt-in.
    */
   evaluations?: boolean | DocsAgentEvaluationsConfig;
 }
@@ -2454,7 +2538,7 @@ interface DocsReviewRulesConfig {
   configConfidence?: DocsReviewSeverity;
   /** Detect disagreement between discovery, resolved config, and the public config schema. */
   agentSurfaceDrift?: DocsReviewSeverity;
-  /** Run deterministic agent golden tasks and report failed or unmeasured behavior. */
+  /** Run configured agent golden tasks and report failed or unmeasured behavior. */
   goldenTasks?: DocsReviewSeverity;
 }
 interface DocsReviewScoreConfig {
@@ -3155,4 +3239,4 @@ interface DocsConfig {
   og?: OGConfig;
 }
 //#endregion
-export { DocsFeedbackValue as $, McpDocsSearchConfig as $t, DocsAnalyticsSource as A, TypesenseDocsSearchConfig as An, DocsSearchDocument as At, DocsCloudFeatureConfig as B, DocsTelemetryEventInput as Bt, DocsAgentTraceEventType as C, SidebarFolderIndexBehavior as Cn, DocsRobotsConfig as Ct, DocsAnalyticsEventInput as D, SidebarTree as Dn, DocsSearchAdapterFactory as Dt, DocsAnalyticsEvent as E, SidebarPageNode as En, DocsSearchAdapterContext as Et, DocsAskAIFeedbackMessage as F, DocsSearchSourcePage as Ft, DocsCodeBlocksPlannerProvider as G, FeedbackConfig as Gt, DocsCloudPublishConfig as H, DocsTelemetryFeatures as Ht, DocsAskAIFeedbackValue as I, DocsSitemapConfig as It, DocsCodeBlocksValidateConfig as J, LastUpdatedConfig as Jt, DocsCodeBlocksRunnerConfig as K, FontStyle as Kt, DocsAskAIMcpConfig as L, DocsTelemetryAgentSurface as Lt, DocsAskAIActionType as M, UIConfig as Mn, DocsSearchQuery as Mt, DocsAskAIFeedbackConfig as N, DocsSearchResult as Nt, DocsAnalyticsEventType as O, SimpleDocsSearchConfig as On, DocsSearchChunkingConfig as Ot, DocsAskAIFeedbackData as P, DocsSearchResultType as Pt, DocsFeedbackData as Q, LlmsTxtSectionConfig as Qt, DocsCloudApiKeyConfig as R, DocsTelemetryConfig as Rt, DocsAgentTraceEventInput as S, SidebarConfig as Sn, DocsReviewSeverity as St, DocsAnalyticsConfig as T, SidebarNode as Tn, DocsSearchAdapter as Tt, DocsCodeBlocksConfig as U, DocsTelemetryFramework as Ut, DocsCloudPreviewConfig as V, DocsTelemetryEventType as Vt, DocsCodeBlocksPlannerConfig as W, DocsTheme as Wt, DocsCodeBlocksValidationPolicy as X, LlmsTxtMaxCharsConfig as Xt, DocsCodeBlocksValidationMode as Y, LlmsTxtConfig as Yt, DocsConfig as Z, LlmsTxtMaxCharsMode as Zt, DocsAgentFeedbackData as _, PageTwitter as _n, DocsReviewCiConfig as _t, ApiReferenceRenderer as a, OpenDocsTarget as an, DocsMcpAuthenticateResult as at, DocsAgentGoldenTaskExpectation as b, ResolvedDocsRelatedLink as bn, DocsReviewRulesConfig as bt, ChangelogFrontmatter as c, PageActionsConfig as cn, DocsMcpOriginContext as ct, CopyMarkdownFormat as d, PageAgentFailureMode as dn, DocsMetadata as dt, OGConfig as en, DocsI18nConfig as et, CustomDocsSearchConfig as f, PageAgentFrontmatter as fn, DocsNav as ft, DocsAgentFeedbackContext as g, PageSidebarFrontmatter as gn, DocsRelatedItem as gt, DocsAgentEvaluationsConfig as h, PageOpenGraph as hn, DocsObservabilityEventInput as ht, ApiReferenceConfig as i, OpenDocsProviderId as in, DocsMcpAuthenticateContext as it, DocsAskAIActionData as j, TypographyConfig as jn, DocsSearchEmbeddingsConfig as jt, DocsAnalyticsInput as k, ThemeToggleConfig as kn, DocsSearchConfig as kt, CodeBlockCopyData as l, PageAgentAppliesTo as ln, DocsMcpSecurityConfig as lt, DocsAgentConfig as m, PageFrontmatter as mn, DocsObservabilityEvent as mt, AgentFeedbackConfig as n, OpenDocsProvider as nn, DocsMcpAuthPrincipal as nt, BreadcrumbConfig as o, OpenGraphImage as on, DocsMcpConfig as ot, DocsAgentCompactConfig as p, PageAgentVerification as pn, DocsObservabilityConfig as pt, DocsCodeBlocksRunnerProvider as q, GithubConfig as qt, AlgoliaDocsSearchConfig as r, OpenDocsProviderConfig as rn, DocsMcpAuthenticate as rt, ChangelogConfig as s, OrderingItem as sn, DocsMcpCorsConfig as st, AIConfig as t, OpenDocsConfig as tn, DocsMcpAllowedOrigins as tt, CopyMarkdownConfig as u, PageAgentCommand as un, DocsMcpToolsConfig as ut, DocsAgentGoldenExpectedExample as v, ReadingTimeConfig as vn, DocsReviewCiMode as vt, DocsAgentTraceStatus as w, SidebarFolderNode as wn, DocsRobotsRule as wt, DocsAgentGoldenTaskFilters as x, SidebarComponentProps as xn, DocsReviewScoreConfig as xt, DocsAgentGoldenTask as y, ReadingTimeFormat as yn, DocsReviewConfig as yt, DocsCloudConfig as z, DocsTelemetryEvent as zt };
+export { DocsCodeBlocksConfig as $, DocsTelemetryFramework as $t, DocsAgentGoldenTaskExpectation as A, ResolvedDocsRelatedLink as An, DocsReviewRulesConfig as At, DocsAnalyticsSource as B, TypesenseDocsSearchConfig as Bn, DocsSearchDocument as Bt, DocsAgentEvaluationsConfig as C, PageAgentVerification as Cn, DocsObservabilityConfig as Ct, DocsAgentGoldenExampleVerification as D, PageTwitter as Dn, DocsReviewCiConfig as Dt, DocsAgentGoldenAnswerExpectation as E, PageSidebarFrontmatter as En, DocsRelatedItem as Et, DocsAnalyticsConfig as F, SidebarNode as Fn, DocsSearchAdapter as Ft, DocsAskAIFeedbackMessage as G, DocsSearchSourcePage as Gt, DocsAskAIActionType as H, UIConfig as Hn, DocsSearchQuery as Ht, DocsAnalyticsEvent as I, SidebarPageNode as In, DocsSearchAdapterContext as It, DocsCloudApiKeyConfig as J, DocsTelemetryConfig as Jt, DocsAskAIFeedbackValue as K, DocsSitemapConfig as Kt, DocsAnalyticsEventInput as L, SidebarTree as Ln, DocsSearchAdapterFactory as Lt, DocsAgentTraceEventInput as M, SidebarConfig as Mn, DocsReviewSeverity as Mt, DocsAgentTraceEventType as N, SidebarFolderIndexBehavior as Nn, DocsRobotsConfig as Nt, DocsAgentGoldenExpectedExample as O, ReadingTimeConfig as On, DocsReviewCiMode as Ot, DocsAgentTraceStatus as P, SidebarFolderNode as Pn, DocsRobotsRule as Pt, DocsCloudPublishConfig as Q, DocsTelemetryFeatures as Qt, DocsAnalyticsEventType as R, SimpleDocsSearchConfig as Rn, DocsSearchChunkingConfig as Rt, DocsAgentEvaluationTaskInput as S, PageAgentFrontmatter as Sn, DocsNav as St, DocsAgentFeedbackData as T, PageOpenGraph as Tn, DocsObservabilityEventInput as Tt, DocsAskAIFeedbackConfig as U, DocsSearchResult as Ut, DocsAskAIActionData as V, TypographyConfig as Vn, DocsSearchEmbeddingsConfig as Vt, DocsAskAIFeedbackData as W, DocsSearchResultType as Wt, DocsCloudFeatureConfig as X, DocsTelemetryEventInput as Xt, DocsCloudConfig as Y, DocsTelemetryEvent as Yt, DocsCloudPreviewConfig as Z, DocsTelemetryEventType as Zt, DocsAgentEvaluationAnswerRequest as _, OrderingItem as _n, DocsMcpCorsConfig as _t, ApiReferenceRenderer as a, LlmsTxtConfig as an, DocsCodeBlocksValidationMode as at, DocsAgentEvaluationSourceReference as b, PageAgentCommand as bn, DocsMcpToolsConfig as bt, ChangelogFrontmatter as c, LlmsTxtSectionConfig as cn, DocsFeedbackData as ct, CopyMarkdownFormat as d, OpenDocsConfig as dn, DocsMcpAllowedOrigins as dt, DocsTheme as en, DocsCodeBlocksPlannerConfig as et, CustomDocsSearchConfig as f, OpenDocsProvider as fn, DocsMcpAuthPrincipal as ft, DocsAgentEvaluationAnswerProvider as g, OpenGraphImage as gn, DocsMcpConfig as gt, DocsAgentEvaluationAnswerInput as h, OpenDocsTarget as hn, DocsMcpAuthenticateResult as ht, ApiReferenceConfig as i, LastUpdatedConfig as in, DocsCodeBlocksValidateConfig as it, DocsAgentGoldenTaskFilters as j, SidebarComponentProps as jn, DocsReviewScoreConfig as jt, DocsAgentGoldenTask as k, ReadingTimeFormat as kn, DocsReviewConfig as kt, CodeBlockCopyData as l, McpDocsSearchConfig as ln, DocsFeedbackValue as lt, DocsAgentConfig as m, OpenDocsProviderId as mn, DocsMcpAuthenticateContext as mt, AgentFeedbackConfig as n, FontStyle as nn, DocsCodeBlocksRunnerConfig as nt, BreadcrumbConfig as o, LlmsTxtMaxCharsConfig as on, DocsCodeBlocksValidationPolicy as ot, DocsAgentCompactConfig as p, OpenDocsProviderConfig as pn, DocsMcpAuthenticate as pt, DocsAskAIMcpConfig as q, DocsTelemetryAgentSurface as qt, AlgoliaDocsSearchConfig as r, GithubConfig as rn, DocsCodeBlocksRunnerProvider as rt, ChangelogConfig as s, LlmsTxtMaxCharsMode as sn, DocsConfig as st, AIConfig as t, FeedbackConfig as tn, DocsCodeBlocksPlannerProvider as tt, CopyMarkdownConfig as u, OGConfig as un, DocsI18nConfig as ut, DocsAgentEvaluationAnswerResult as v, PageActionsConfig as vn, DocsMcpOriginContext as vt, DocsAgentFeedbackContext as w, PageFrontmatter as wn, DocsObservabilityEvent as wt, DocsAgentEvaluationSurface as x, PageAgentFailureMode as xn, DocsMetadata as xt, DocsAgentEvaluationAnswerRunner as y, PageAgentAppliesTo as yn, DocsMcpSecurityConfig as yt, DocsAnalyticsInput as z, ThemeToggleConfig as zn, DocsSearchConfig as zt };

package/dist/{upgrade-CXYRNV0C.mjs → upgrade-BCJTCW3O.mjs}

@@ -1,5 +1,5 @@
-import { c as fileExists, o as exec } from "./utils-DBCCkkJS.mjs";
-import { a as getPackagesForFramework, c as resolveDocsPackageManager, i as frameworkFromPreset, l as validateUpgradeVersion, n as PRESETS, o as presetFromFramework, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework, t as PACKAGES_BY_FRAMEWORK } from "./package-version-DRIc08EU.mjs";
+import { c as fileExists, o as exec } from "./utils-6UCLxv4B.mjs";
+import { a as getPackagesForFramework, c as resolveDocsPackageManager, i as frameworkFromPreset, l as validateUpgradeVersion, n as PRESETS, o as presetFromFramework, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework, t as PACKAGES_BY_FRAMEWORK } from "./package-version-qik_4J6C.mjs";
 import path from "node:path";
 import pc from "picocolors";
 import * as p from "@clack/prompts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.2.57",
+  "version": "0.2.58",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",