diff --git a/src/lib/assertions/javascript.ts b/src/lib/assertions/javascript.ts
index e918516..4b63206 100644
--- a/src/lib/assertions/javascript.ts
+++ b/src/lib/assertions/javascript.ts
@@ -20,6 +20,7 @@ const jsResultSchema = assertionResultSchema.extend({
   outputs: z.record(z.string(), z.union([z.boolean(), z.number()])).optional(),
 });
 type JsResult = z.infer<typeof jsResultSchema>;
+export type JavascriptAssertionArgs = z.infer<typeof argsSchema>;
 
 export function createJavascriptAssertion(
   args: unknown,
diff --git a/src/lib/documentation/codeReferenceTypes.compat.ts b/src/lib/documentation/codeReferenceTypes.compat.ts
new file mode 100644
index 0000000..fb8e25e
--- /dev/null
+++ b/src/lib/documentation/codeReferenceTypes.compat.ts
@@ -0,0 +1,244 @@
+import type { JavascriptAssertionArgs } from '$lib/assertions/javascript';
+import type { CodeReference, Executable, ModuleExecutable } from '$lib/storage/CodeReference';
+import type { FileReference } from '$lib/storage/FileReference';
+import type {
+  AssertionResult,
+  ConversationPrompt,
+  MultiPartPrompt,
+  NormalizedPipelineStep,
+  NormalizedPrompt,
+  ProviderOutput,
+  ProviderOutputPart,
+  PromptPart,
+  Provider,
+  RolePromptPart,
+  TestOutput,
+  TransformOutput,
+} from '$lib/types';
+import type * as DocTypes from './codeReferenceTypes';
+
+type Assert<T extends true> = T;
+type IsAssignable<A, B> = [A] extends [B] ? true : false;
+type IsMutuallyAssignable<A, B> =
+  IsAssignable<A, B> extends true ? (IsAssignable<B, A> extends true ? true : false) : false;
+
+interface CodeReferencePublic {
+  uri: string;
+  file: File;
+  type: 'file' | 'image' | 'code';
+  bind(): Promise<Executable>;
+  bindModule(): Promise<ModuleExecutable>;
+  getCode(): Promise<string>;
+}
+
+interface CodeReferenceMarker {
+  readonly __codeReference: unique symbol;
+}
+interface FileReferenceMarker {
+  readonly __fileReference: unique symbol;
+}
+type ReplaceCodeReference<T> = T extends CodeReference | DocTypes.CodeReference
+  ? CodeReferenceMarker
+  : T extends FileReference | DocTypes.FileReference
+    ? FileReferenceMarker
+    : T extends File
+      ? File
+      : T extends (infer U)[]
+        ? ReplaceCodeReference<U>[]
+        : T extends object
+          ? { [K in keyof T]: ReplaceCodeReference<T[K]> }
+          : T;
+
+type _CodeReferenceActual = Assert<IsAssignable<CodeReference, CodeReferencePublic>>;
+type _CodeReferenceDoc = Assert<IsAssignable<DocTypes.CodeReference, CodeReferencePublic>>;
+type _Executable = Assert<IsMutuallyAssignable<DocTypes.Executable, Executable>>;
+type _ModuleExecutable = Assert<IsMutuallyAssignable<DocTypes.ModuleExecutable, ModuleExecutable>>;
+type PromptPartShape =
+  | { text: string }
+  | { file: File }
+  | {
+      type: 'function-call';
+      name: string;
+      args: unknown;
+      meta: unknown;
+    }
+  | {
+      type: 'function-response';
+      call: {
+        type: 'function-call';
+        name: string;
+        args: unknown;
+        meta: unknown;
+      };
+      response: unknown;
+    };
+
+type _PromptPartDocText = Assert<IsAssignable<{ text: string }, DocTypes.PromptPart>>;
+type _PromptPartActualText = Assert<IsAssignable<{ text: string }, PromptPart>>;
+type _PromptPartDocFile = Assert<IsAssignable<{ file: File }, DocTypes.PromptPart>>;
+type _PromptPartActualFile = Assert<IsAssignable<{ file: File }, PromptPart>>;
+type _PromptPartDocCall = Assert<
+  IsAssignable<
+    { type: 'function-call'; name: string; args: unknown; meta: unknown },
+    DocTypes.PromptPart
+  >
+>;
+type _PromptPartActualCall = Assert<
+  IsAssignable<{ type: 'function-call'; name: string; args: unknown; meta: unknown }, PromptPart>
+>;
+type _PromptPartDocResponse = Assert<
+  IsAssignable<
+    {
+      type: 'function-response';
+      call: { type: 'function-call'; name: string; args: unknown; meta: unknown };
+      response: unknown;
+    },
+    DocTypes.PromptPart
+  >
+>;
+type _PromptPartActualResponse = Assert<
+  IsAssignable<
+    {
+      type: 'function-response';
+      call: { type: 'function-call'; name: string; args: unknown; meta: unknown };
+      response: unknown;
+    },
+    PromptPart
+  >
+>;
+type _MultiPartPromptDoc = Assert<
+  IsMutuallyAssignable<DocTypes.MultiPartPrompt, DocTypes.PromptPart[]>
+>;
+type _MultiPartPromptActual = Assert<IsMutuallyAssignable<MultiPartPrompt, PromptPart[]>>;
+type _RolePromptPartDoc = Assert<
+  IsMutuallyAssignable<
+    DocTypes.RolePromptPart,
+    { role: RolePromptPart['role']; content: DocTypes.MultiPartPrompt }
+  >
+>;
+type _RolePromptPartActual = Assert<
+  IsMutuallyAssignable<RolePromptPart, { role: RolePromptPart['role']; content: MultiPartPrompt }>
+>;
+type _ConversationPromptDoc = Assert<
+  IsMutuallyAssignable<DocTypes.ConversationPrompt, DocTypes.RolePromptPart[]>
+>;
+type _ConversationPromptActual = Assert<IsMutuallyAssignable<ConversationPrompt, RolePromptPart[]>>;
+
+type _PromptPartShape = Assert<IsAssignable<DocTypes.PromptPart, PromptPartShape>>;
+type _Provider = Assert<
+  IsMutuallyAssignable<ReplaceCodeReference<DocTypes.Provider>, ReplaceCodeReference<Provider>>
+>;
+type _JavascriptAssertionArgs = Assert<
+  IsMutuallyAssignable<
+    ReplaceCodeReference<DocTypes.JavascriptAssertionArgs>,
+    ReplaceCodeReference<JavascriptAssertionArgs>
+  >
+>;
+interface ExpectedJavascriptAssertionResult {
+  pass: boolean;
+  message?: string;
+  visuals?: (string | Blob)[];
+  outputs?: Record<string, boolean | number>;
+}
+type _JavascriptAssertionResult = Assert<
+  IsMutuallyAssignable<DocTypes.JavascriptAssertionResult, ExpectedJavascriptAssertionResult>
+>;
+type _ProviderOutput = Assert<
+  IsAssignable<ReplaceCodeReference<DocTypes.ProviderOutput>, ReplaceCodeReference<ProviderOutput>>
+>;
+type _ProviderOutputPart = Assert<
+  IsAssignable<
+    ReplaceCodeReference<DocTypes.ProviderOutputPart>,
+    ReplaceCodeReference<ProviderOutputPart>
+  >
+>;
+type _TransformOutput = Assert<
+  IsAssignable<
+    ReplaceCodeReference<DocTypes.TransformOutput>,
+    ReplaceCodeReference<TransformOutput>
+  >
+>;
+type _TestOutput = Assert<
+  IsAssignable<ReplaceCodeReference<DocTypes.TestOutput>, ReplaceCodeReference<TestOutput>>
+>;
+type _NormalizedPrompt = Assert<
+  IsAssignable<
+    ReplaceCodeReference<DocTypes.NormalizedPrompt>,
+    ReplaceCodeReference<NormalizedPrompt>
+  >
+>;
+type _AssertionResult = Assert<
+  IsAssignable<
+    ReplaceCodeReference<DocTypes.AssertionResult>,
+    ReplaceCodeReference<AssertionResult>
+  >
+>;
+type _PipelineIf = Assert<
+  IsMutuallyAssignable<
+    ReplaceCodeReference<DocTypes.PipelineIf>,
+    ReplaceCodeReference<NormalizedPipelineStep['if']>
+  >
+>;
+type _PipelineTransform = Assert<
+  IsMutuallyAssignable<
+    ReplaceCodeReference<DocTypes.PipelineTransform>,
+    ReplaceCodeReference<NormalizedPipelineStep['transform']>
+  >
+>;
+
+type ExpectedPromptTransformHandler = (
+  output: DocTypes.ProviderOutput,
+  context: { vars: DocTypes.PipelineVars },
+) =>
+  | DocTypes.TransformOutput
+  | DocTypes.TransformResult
+  | Promise<DocTypes.TransformOutput | DocTypes.TransformResult>;
+
+type ExpectedPromptIfHandler = (vars: DocTypes.PipelineVars) => boolean | Promise<boolean>;
+
+type ExpectedProviderPrepareHandler = (
+  prompt: DocTypes.ConversationPrompt,
+  context: DocTypes.ProviderConfigContext,
+) => DocTypes.MaybePromise<unknown>;
+
+type ExpectedProviderRunHandler = (
+  key: unknown,
+  context: DocTypes.ProviderConfigContext,
+) =>
+  | string
+  | (string | Blob | DocTypes.MetaProviderOutputPart)[]
+  | DocTypes.MaybePromise<string | (string | Blob | DocTypes.MetaProviderOutputPart)[]>;
+
+type ExpectedProviderEnvHandler = () => DocTypes.MaybePromise<string[]>;
+
+type ExpectedAssertionCellHandler = (
+  output: DocTypes.ProviderOutput,
+  context: DocTypes.AssertionCellContext,
+) => DocTypes.MaybePromise<DocTypes.JavascriptAssertionResult>;
+
+type ExpectedAssertionRowHandler = (
+  results: DocTypes.TestOutput[],
+  context: DocTypes.AssertionRowContext,
+) => DocTypes.MaybePromise<DocTypes.JavascriptAssertionResult[]>;
+
+type _PromptTransformHandler = Assert<
+  IsMutuallyAssignable<DocTypes.PromptTransformHandler, ExpectedPromptTransformHandler>
+>;
+type _PromptIfHandler = Assert<
+  IsMutuallyAssignable<DocTypes.PromptIfHandler, ExpectedPromptIfHandler>
+>;
+type _ProviderPrepareHandler = Assert<
+  IsMutuallyAssignable<DocTypes.ProviderPrepareHandler, ExpectedProviderPrepareHandler>
+>;
+type _ProviderRunHandler = Assert<
+  IsMutuallyAssignable<DocTypes.ProviderRunHandler, ExpectedProviderRunHandler>
+>;
+type _ProviderEnvHandler = Assert<
+  IsMutuallyAssignable<DocTypes.ProviderEnvHandler, ExpectedProviderEnvHandler>
+>;
+type _AssertionCellHandler = Assert<
+  IsMutuallyAssignable<DocTypes.AssertionCellHandler, ExpectedAssertionCellHandler>
+>;
+type _AssertionRowHandler = Assert<
+  IsMutuallyAssignable<DocTypes.AssertionRowHandler, ExpectedAssertionRowHandler>
+>;
diff --git a/src/lib/documentation/codeReferenceTypes.ts b/src/lib/documentation/codeReferenceTypes.ts
new file mode 100644
index 0000000..fea0dfa
--- /dev/null
+++ b/src/lib/documentation/codeReferenceTypes.ts
@@ -0,0 +1,187 @@
+// Self-contained CodeReference-related type definitions for docs/downloads.
+// This file must not import from $lib or any other local modules.
+
+export type Executable = (...args: unknown[]) => Promise<unknown>;
+export type ModuleExecutable = (name: string | undefined, ...args: unknown[]) => Promise<unknown>;
+
+export declare class FileReference {
+  readonly uri: string;
+  readonly file: File;
+  readonly type: 'file' | 'image' | 'code';
+  constructor(uri: string, file: File, type?: 'file' | 'image' | 'code');
+}
+
+export declare class CodeReference extends FileReference {
+  bind(): Promise<Executable>;
+  bindModule(): Promise<ModuleExecutable>;
+  getCode(): Promise<string>;
+}
+
+export type CodeReferenceInput = string | CodeReference;
+export type PipelineIf = string | CodeReference | undefined;
+export type PipelineTransform = string | CodeReference | undefined;
+
+export interface FunctionCall {
+  type: 'function-call';
+  name: string;
+  args: unknown;
+  meta: unknown;
+}
+export interface FunctionResponse {
+  type: 'function-response';
+  call: FunctionCall;
+  response: unknown;
+}
+export type FunctionTool = FunctionCall | FunctionResponse;
+
+export interface MetaMessagePart {
+  type: 'meta';
+  title: string;
+  icon: 'thinking' | 'search' | 'code' | 'other';
+  message: string;
+  data?: unknown;
+}
+export type MetaProviderOutputPart = MetaMessagePart | FunctionCall | FunctionResponse;
+
+export type PromptPart = { text: string } | { file: File } | FunctionTool;
+export type MultiPartPrompt = PromptPart[];
+export interface RolePromptPart {
+  role: 'user' | 'assistant' | 'system';
+  content: MultiPartPrompt;
+}
+export type ConversationPrompt = RolePromptPart[];
+export type ProviderOutputPart = string | FileReference | MetaProviderOutputPart;
+export type ProviderOutput = string | ProviderOutputPart[];
+
+export interface JavascriptAssertionArgs {
+  code: string | CodeReference;
+  row?: boolean;
+}
+export interface JavascriptAssertionResult {
+  pass: boolean;
+  message?: string;
+  visuals?: (string | Blob)[];
+  outputs?: Record<string, boolean | number>;
+}
+
+export type ProviderId = string | CodeReference;
+export interface NormalizedProviderConfig extends Record<string, unknown> {
+  mimeTypes?: string[];
+}
+export interface ProviderDefinition {
+  id: ProviderId;
+  labels?: string[];
+  config?: NormalizedProviderConfig;
+  env?: string[];
+  prompts?: string[];
+}
+export type Provider = string | CodeReference | ProviderDefinition;
+
+export type Var = unknown;
+export type VarSet = Record<string, Var>;
+
+export interface AssertionResult {
+  pass: boolean;
+  message?: string;
+  visuals?: (string | FileReference)[];
+  outputs?: Record<string, boolean | number>;
+  id?: string;
+}
+
+export interface TokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  costDollars?: number;
+}
+
+export interface TestOutput {
+  rawPrompt: unknown;
+  rawOutput?: unknown;
+  output?: ProviderOutput;
+  latencyMillis?: number;
+  tokenUsage?: TokenUsage;
+  error?: string;
+}
+
+export interface NormalizedPipelineStep {
+  id: string;
+  prompt?: string;
+  outputAs?: string;
+  if?: string | CodeReference;
+  deps?: string[];
+  providerLabel?: string;
+  session?: string | boolean;
+  functionCalls?: 'loop' | 'once' | 'never';
+  transform?: string | CodeReference;
+  state?: string[];
+}
+export interface NormalizedPipelinePrompt {
+  $pipeline: NormalizedPipelineStep[];
+}
+export type NormalizedPrompt =
+  | string
+  | { prompt: string; providerLabel?: string }
+  | NormalizedPipelinePrompt;
+
+export interface HistoryItem {
+  id: string;
+  prompt: ConversationPrompt;
+  output: ProviderOutput;
+}
+export interface PipelineVars extends VarSet {
+  $output: ProviderOutput | null;
+  $history: HistoryItem[];
+  $state?: VarSet;
+  $args?: unknown;
+}
+
+export type TransformOutput = string | (string | Blob | MetaProviderOutputPart)[];
+export interface TransformResult {
+  vars?: VarSet;
+  output?: TransformOutput;
+}
+
+export interface ProviderConfigContext {
+  env: Record<string, string>;
+  config: Record<string, unknown>;
+}
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type PromptTransformHandler = (
+  output: ProviderOutput,
+  context: { vars: PipelineVars },
+) => MaybePromise<TransformOutput | TransformResult>;
+
+export type PromptIfHandler = (vars: PipelineVars) => MaybePromise<boolean>;
+
+export type ProviderPrepareHandler = (
+  prompt: ConversationPrompt,
+  context: ProviderConfigContext,
+) => MaybePromise<unknown>;
+
+export type ProviderRunOutput = string | (string | Blob | MetaProviderOutputPart)[];
+
+export type ProviderRunHandler = (
+  key: unknown,
+  context: ProviderConfigContext,
+) => MaybePromise<ProviderRunOutput>;
+
+export type ProviderEnvHandler = () => MaybePromise<string[]>;
+
+export interface AssertionCellContext {
+  provider: { id: string | CodeReference | null; labeled?: Record<string, { id: string }> };
+  prompt: NormalizedPrompt;
+}
+export interface AssertionRowContext {
+  prompts: NormalizedPrompt[];
+}
+export type AssertionCellHandler = (
+  output: ProviderOutput,
+  context: AssertionCellContext,
+) => MaybePromise<JavascriptAssertionResult>;
+export type AssertionRowHandler = (
+  results: TestOutput[],
+  context: AssertionRowContext,
+) => MaybePromise<JavascriptAssertionResult[]>;
diff --git a/src/lib/storage/runGenerators.ts b/src/lib/storage/runGenerators.ts
index c007613..a9b8f94 100644
--- a/src/lib/storage/runGenerators.ts
+++ b/src/lib/storage/runGenerators.ts
@@ -4,7 +4,7 @@ import { getFileExtension } from '$lib/utils/path';
 import { CodeReference, toCodeReference } from './CodeReference';
 import { FileReference } from './FileReference';
 
-interface Generator {
+export interface Generator {
   '=gen': string | CodeReference;
   args?: unknown[];
 }
diff --git a/src/lib/storage/types.ts b/src/lib/storage/types.ts
index c5db971..23a503e 100644
--- a/src/lib/storage/types.ts
+++ b/src/lib/storage/types.ts
@@ -35,6 +35,7 @@ export const fsProviderSchema = z.union([
   z.instanceof(CodeReference),
   fsExpandedProviderSchema,
 ]);
+export type FsProvider = z.infer<typeof fsProviderSchema>;
 
 export const fsConvoPromptSchema = z.array(
   z.union([
diff --git a/src/routes/documentation/+page.md b/src/routes/documentation/+page.md
index b3ac19f..b9023dd 100644
--- a/src/routes/documentation/+page.md
+++ b/src/routes/documentation/+page.md
@@ -10,6 +10,8 @@ _**Want AI to write your evals?** Check out [our llms.txt](/llms.txt). You can c
 
 _**Looking for a reference for configuration files?** Check [here](/documentation/config)._
 
+_**Need the full CodeReference TypeScript definitions?** Grab the copy/download-ready file [here](/documentation/code-reference-types)._
+
 First, create a folder where your evaluation data and output will be stored. Create an `evals.yaml` file inside it and add the following:
 
 ```yaml
diff --git a/src/routes/documentation/code-reference-types/+page.svelte b/src/routes/documentation/code-reference-types/+page.svelte
new file mode 100644
index 0000000..f762205
--- /dev/null
+++ b/src/routes/documentation/code-reference-types/+page.svelte
@@ -0,0 +1,21 @@
+<script lang="ts">
+  import codeReferenceTypes from '$lib/documentation/codeReferenceTypes.ts?raw';
+
+  const downloadUrl = '/documentation/code-reference-types/types';
+</script>
+
+<svelte:head>
+  <title>CodeReference Types</title>
+</svelte:head>
+
+<div class="prose max-w-none">
+  <h1>CodeReference Types</h1>
+  <p>
+    Copy the TypeScript definitions below or
+    <a href={downloadUrl} download="code-reference-types.ts">download the file</a>
+    to keep all CodeReference-related types in sync with your project. This file is generated directly
+    from the source types, so it stays aligned as we evolve the API.
+  </p>
+
+  <pre><code>{codeReferenceTypes}</code></pre>
+</div>
diff --git a/src/routes/documentation/code-reference-types/types/+server.ts b/src/routes/documentation/code-reference-types/types/+server.ts
new file mode 100644
index 0000000..ddb7e08
--- /dev/null
+++ b/src/routes/documentation/code-reference-types/types/+server.ts
@@ -0,0 +1,11 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import codeReferenceTypes from '$lib/documentation/codeReferenceTypes.ts?raw';
+
+export const GET: RequestHandler = () => {
+  return new Response(codeReferenceTypes, {
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+      'Content-Disposition': 'attachment; filename="code-reference-types.ts"',
+    },
+  });
+};