@labelbox/rl-sdk 0.0.0

package/dist/reference/recipes-schema.d.ts

@@ -0,0 +1,676 @@
+import { z } from 'zod';
+/**
+ * How often a recipe is validated — an **internal CI cadence**, never surfaced
+ * in the docs (deliberately not on `RecipeReferenceEntry`):
+ *   - `'per-merge'` — rides the post-deploy smoke on every merge.
+ *   - `{ everyDays: N }` — pulled out of the per-merge smoke; validated by the
+ *     daily workflow only on the days it's "due" (date-modulo schedule).
+ * A future weekly tier is just `{ everyDays: 7 }` — no schema change.
+ */
+export declare const RecipeCadenceSchema: z.ZodUnion<readonly [z.ZodLiteral<"per-merge">, z.ZodObject<{
+    everyDays: z.ZodNumber;
+}, z.core.$strict>]>;
+export type RecipeCadence = z.infer<typeof RecipeCadenceSchema>;
+/** A link to another **recipe** (traversable — the agent can follow it). */
+export declare const RecipeRecipeTargetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"recipe">;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** A link to a **concept** (Explanation) page declared in `CONCEPT_REFERENCE`. */
+export declare const RecipeConceptTargetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"concept">;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** A link to a **tutorial** page. */
+export declare const RecipeTutorialTargetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tutorial">;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** A link to a **resource** page. */
+export declare const RecipeResourceTargetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"resource">;
+    id: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Any typed link target (`recipe | concept | tutorial | resource`). One typed
+ * model lets a recipe reference *any* doc element — relationships aren't only
+ * between recipes — instead of a separate field per kind.
+ */
+export declare const RecipeLinkTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"recipe">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"concept">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"tutorial">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"resource">;
+    id: z.ZodString;
+}, z.core.$strict>], "type">;
+export type RecipeLinkTarget = z.infer<typeof RecipeLinkTargetSchema>;
+/**
+ * A `learnMore` target — the "why" behind the how-to: a concept / tutorial /
+ * resource. NOT a recipe (a recipe demonstrates; a concept explains — pairing
+ * them is what teaches the reader). The concept page lists its recipes via the
+ * inverse, so there's no second "taught by" field.
+ */
+export declare const RecipeLearnMoreTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"concept">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"tutorial">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"resource">;
+    id: z.ZodString;
+}, z.core.$strict>], "type">;
+export type RecipeLearnMoreTarget = z.infer<typeof RecipeLearnMoreTargetSchema>;
+/**
+ * A `requires` entry that is a **state precondition** rather than a recipe — the
+ * common "the version must be locked" case that has no recipe of its own. It
+ * carries a human `explanation`, an optional machine-checkable `predicate`
+ * (e.g. `version.locked === true` — in L0 only *stored* and required to be a
+ * non-empty string; *evaluated* in a later layer), and an optional `via` link to
+ * whatever reaches the state (a recipe / concept / tutorial / resource).
+ */
+export declare const RecipeStateRequirementSchema: z.ZodObject<{
+    type: z.ZodLiteral<"state">;
+    explanation: z.ZodString;
+    predicate: z.ZodOptional<z.ZodString>;
+    via: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"recipe">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"concept">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"tutorial">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"resource">;
+        id: z.ZodString;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+export type RecipeStateRequirement = z.infer<typeof RecipeStateRequirementSchema>;
+/**
+ * A typed prerequisite: another **recipe** (a real, followable edge — "author a
+ * problem before grading it") or a **state** precondition (the explanation +
+ * optional predicate above). The backbone an agent traverses off the `now what?`
+ * cliff.
+ */
+export declare const RecipeRequiresEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"recipe">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"state">;
+    explanation: z.ZodString;
+    predicate: z.ZodOptional<z.ZodString>;
+    via: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"recipe">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"concept">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"tutorial">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"resource">;
+        id: z.ZodString;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>], "type">;
+export type RecipeRequiresEntry = z.infer<typeof RecipeRequiresEntrySchema>;
+/**
+ * The optional `related` block on a recipe — its place in the graph. All fields
+ * optional; an absent block means "no declared relationships" (an island, which
+ * `recipes:check` permits but the docs nudge away from).
+ */
+export declare const RecipeRelatedSchema: z.ZodObject<{
+    requires: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"recipe">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"state">;
+        explanation: z.ZodString;
+        predicate: z.ZodOptional<z.ZodString>;
+        via: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"recipe">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"concept">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"tutorial">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"resource">;
+            id: z.ZodString;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>], "type">>>;
+    variationOf: z.ZodOptional<z.ZodString>;
+    learnMore: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"concept">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"tutorial">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"resource">;
+        id: z.ZodString;
+    }, z.core.$strict>], "type">>>;
+}, z.core.$strict>;
+export type RecipeRelated = z.infer<typeof RecipeRelatedSchema>;
+/** A recipe's identity + docs metadata (`manifest.ts`). */
+export declare const RecipeManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    goal: z.ZodString;
+    category: z.ZodString;
+    cadence: z.ZodUnion<readonly [z.ZodLiteral<"per-merge">, z.ZodObject<{
+        everyDays: z.ZodNumber;
+    }, z.core.$strict>]>;
+    stepDescriptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    outcomeInUiOnly: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    related: z.ZodOptional<z.ZodObject<{
+        requires: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"recipe">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"state">;
+            explanation: z.ZodString;
+            predicate: z.ZodOptional<z.ZodString>;
+            via: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"recipe">;
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"concept">;
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"tutorial">;
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"resource">;
+                id: z.ZodString;
+            }, z.core.$strict>], "type">>;
+        }, z.core.$strict>], "type">>>;
+        variationOf: z.ZodOptional<z.ZodString>;
+        learnMore: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"concept">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"tutorial">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"resource">;
+            id: z.ZodString;
+        }, z.core.$strict>], "type">>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RecipeManifest = z.infer<typeof RecipeManifestSchema>;
+/** A reference to a value captured by an earlier step (threading). */
+export declare const RecipeRefSchema: z.ZodObject<{
+    $ref: z.ZodString;
+}, z.core.$strict>;
+export type RecipeRef = z.infer<typeof RecipeRefSchema>;
+/**
+ * An input supplied to one of a step's params:
+ *   - `{ $ref: '<captureName>' }` — threaded from an earlier step's capture.
+ *   - `{ value: <json> }`         — a literal rendered verbatim in the examples.
+ * Params not listed in a step's `inputs` render as placeholders (user-supplied).
+ */
+export declare const RecipeInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    $ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    value: z.ZodUnknown;
+}, z.core.$strict>]>;
+export type RecipeInput = z.infer<typeof RecipeInputSchema>;
+/**
+ * A **poll** modifier on an SDK step: re-invoke this operation on an interval
+ * until it reaches a terminal state, *then* read its captures off that terminal
+ * response. This makes "wait for the result, then read it" a first-class,
+ * **documented** part of the recipe (rendered as a real loop in the SDK/CLI/cURL
+ * examples) rather than hidden test scaffolding — a recipe teaches the reader how
+ * to wait, exactly as the UI walkthrough does. The executor (`executeApiPlan`):
+ *   - fails RED when `failOn` is set and its condition holds — `failOn.path`'s
+ *     value is in `failOn.in` (or, with `present`, is non-null). Checked FIRST,
+ *     so a terminal failure is surfaced, never masked by a coincident `until`.
+ *   - stops successfully when `until` holds — `until.path`'s value is in
+ *     `until.in`, or (with `present`) is non-null (e.g. `finalScore` landing).
+ *   - fails RED when `timeoutMs` elapses first.
+ * Poll is SDK-only (an Intelligence step has no `operationId` to re-invoke).
+ */
+export declare const RecipePollSchema: z.ZodObject<{
+    until: z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+        in: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        path: z.ZodString;
+        present: z.ZodLiteral<true>;
+    }, z.core.$strict>]>;
+    failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+        in: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        path: z.ZodString;
+        present: z.ZodLiteral<true>;
+    }, z.core.$strict>]>>;
+    timeoutMs: z.ZodNumber;
+    intervalMs: z.ZodNumber;
+}, z.core.$strict>;
+export type RecipePoll = z.infer<typeof RecipePollSchema>;
+/**
+ * An SDK step — today's `operationId`-based call. `setup` steps render as a
+ * marked preamble (each recipe provisions its own setup); `main` steps are the
+ * goal proper. `kind` defaults to `'sdk'` so existing (kind-less) recipes stay
+ * valid and the common case needs no `kind:` line.
+ */
+export declare const RecipeSdkStepSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodLiteral<"sdk">>;
+    operationId: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+    phase: z.ZodDefault<z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>>;
+    inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        $ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        value: z.ZodUnknown;
+    }, z.core.$strict>]>>>;
+    poll: z.ZodOptional<z.ZodObject<{
+        until: z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>;
+        failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>>;
+        timeoutMs: z.ZodNumber;
+        intervalMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    captures: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type RecipeSdkStep = z.infer<typeof RecipeSdkStepSchema>;
+/**
+ * An Intelligence (Labelbox) step — a raw GraphQL command POSTed to
+ * `${LBX_URL}/api/_gql` with the SAME `Authorization: Bearer <LABELBOX_API_KEY>`
+ * the rl SDK/CLI already use. This surfaces the parts of a real flow that have
+ * no rl-gym SDK route (create a project, add a labeler, submit/review) so an
+ * agent reading the recipe gets the *complete* journey, not just the SDK slice.
+ * `caption` is REQUIRED — it is the user-facing instruction ("Create a project
+ * in Intelligence") that the whole feature exists to surface. `{ $ref }` markers
+ * embedded in `gql.variables` thread in earlier captures; `captures` reads
+ * fields off the GraphQL response's `data` object (e.g. `createProject.id`).
+ */
+export declare const RecipeIntelligenceStepSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"intelligence">;
+    caption: z.ZodString;
+    phase: z.ZodDefault<z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>>;
+    gql: z.ZodObject<{
+        query: z.ZodString;
+        variables: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    captures: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type RecipeIntelligenceStep = z.infer<typeof RecipeIntelligenceStepSchema>;
+/**
+ * One step of a recipe's `api.ts`: an SDK call or an Intelligence GraphQL
+ * command. A plain `z.union` (not `discriminatedUnion`) is deliberate — Zod 4's
+ * `discriminatedUnion` reads the discriminator BEFORE applying defaults, so a
+ * `kind`-less step would fail to match; `z.union` tries the SDK variant first,
+ * whose defaulted `kind` absorbs the omitted discriminator. TypeScript still
+ * narrows on the `kind` literal at the consumer.
+ */
+export declare const RecipeApiStepSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodDefault<z.ZodLiteral<"sdk">>;
+    operationId: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+    phase: z.ZodDefault<z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>>;
+    inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        $ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        value: z.ZodUnknown;
+    }, z.core.$strict>]>>>;
+    poll: z.ZodOptional<z.ZodObject<{
+        until: z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>;
+        failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>>;
+        timeoutMs: z.ZodNumber;
+        intervalMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    captures: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"intelligence">;
+    caption: z.ZodString;
+    phase: z.ZodDefault<z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>>;
+    gql: z.ZodObject<{
+        query: z.ZodString;
+        variables: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    captures: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>]>;
+export type RecipeApiStep = z.infer<typeof RecipeApiStepSchema>;
+/** The ordered API plan for a recipe (`api.ts`). */
+export declare const RecipeApiSchema: z.ZodObject<{
+    steps: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodDefault<z.ZodLiteral<"sdk">>;
+        operationId: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
+        phase: z.ZodDefault<z.ZodEnum<{
+            setup: "setup";
+            main: "main";
+        }>>;
+        inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            $ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            value: z.ZodUnknown;
+        }, z.core.$strict>]>>>;
+        poll: z.ZodOptional<z.ZodObject<{
+            until: z.ZodUnion<readonly [z.ZodObject<{
+                path: z.ZodString;
+                in: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                path: z.ZodString;
+                present: z.ZodLiteral<true>;
+            }, z.core.$strict>]>;
+            failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                path: z.ZodString;
+                in: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                path: z.ZodString;
+                present: z.ZodLiteral<true>;
+            }, z.core.$strict>]>>;
+            timeoutMs: z.ZodNumber;
+            intervalMs: z.ZodNumber;
+        }, z.core.$strict>>;
+        captures: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"intelligence">;
+        caption: z.ZodString;
+        phase: z.ZodDefault<z.ZodEnum<{
+            setup: "setup";
+            main: "main";
+        }>>;
+        gql: z.ZodObject<{
+            query: z.ZodString;
+            variables: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>;
+        captures: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+/** Normalized plan (defaults applied) — what the generator consumes post-parse. */
+export type RecipeApi = z.infer<typeof RecipeApiSchema>;
+/** Authoring shape (defaults optional) — what an `api.ts` author writes / `satisfies`. */
+export type RecipeApiInput = z.input<typeof RecipeApiSchema>;
+/** A validated SDK step in the generated reference (phase/inputs/captures normalized). */
+export declare const RecipeSdkReferenceStepSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"sdk">;
+    operationId: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+    phase: z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>;
+    inputs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        $ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        value: z.ZodUnknown;
+    }, z.core.$strict>]>>;
+    poll: z.ZodOptional<z.ZodObject<{
+        until: z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>;
+        failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>>;
+        timeoutMs: z.ZodNumber;
+        intervalMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    captures: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+/** A validated Intelligence step in the generated reference (normalized). */
+export declare const RecipeIntelligenceReferenceStepSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"intelligence">;
+    caption: z.ZodString;
+    phase: z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>;
+    gql: z.ZodObject<{
+        query: z.ZodString;
+        variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>;
+    captures: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+/**
+ * A validated step in the generated reference. The reference is the *normalized*
+ * form (defaults already applied, so `kind` is always present) — a
+ * `discriminatedUnion` is safe here and gives precise per-variant errors.
+ */
+export declare const RecipeReferenceStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"sdk">;
+    operationId: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+    phase: z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>;
+    inputs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        $ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        value: z.ZodUnknown;
+    }, z.core.$strict>]>>;
+    poll: z.ZodOptional<z.ZodObject<{
+        until: z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>;
+        failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            path: z.ZodString;
+            in: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodString;
+            present: z.ZodLiteral<true>;
+        }, z.core.$strict>]>>;
+        timeoutMs: z.ZodNumber;
+        intervalMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    captures: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"intelligence">;
+    caption: z.ZodString;
+    phase: z.ZodEnum<{
+        setup: "setup";
+        main: "main";
+    }>;
+    gql: z.ZodObject<{
+        query: z.ZodString;
+        variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>;
+    captures: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>], "kind">;
+export type RecipeReferenceStep = z.infer<typeof RecipeReferenceStepSchema>;
+/**
+ * One step of the UI **walkthrough** — a user-facing caption next to its
+ * screenshot. Captured from the `ui.spec` run by `recipes:capture-media`
+ * (`image` is a filename under `apps/recursion/web/public/docs/recipes/<id>/`) and
+ * rendered as the docs Walkthrough filmstrip. The caption is page text beside
+ * the image, never burned into it.
+ */
+export declare const RecipeWalkthroughStepSchema: z.ZodObject<{
+    caption: z.ZodString;
+    image: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RecipeWalkthroughStep = z.infer<typeof RecipeWalkthroughStepSchema>;
+/** The committed walkthrough manifest (`walkthrough.json`): an ordered step list. */
+export declare const RecipeWalkthroughSchema: z.ZodArray<z.ZodObject<{
+    caption: z.ZodString;
+    image: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type RecipeWalkthrough = z.infer<typeof RecipeWalkthroughSchema>;
+/**
+ * A composed example for one surface, split by phase: the `setup` preamble
+ * (provisioning steps — `phase: 'setup'`) and the `main` goal steps. The docs
+ * render `setup` as a collapsed disclosure so the recipe's actual point leads;
+ * concatenating `setup` + `main` is the full runnable script. Either may be the
+ * empty string (a recipe with no setup steps, or none in main).
+ */
+export declare const RecipeSnippetSchema: z.ZodObject<{
+    setup: z.ZodString;
+    main: z.ZodString;
+}, z.core.$strict>;
+export type RecipeSnippet = z.infer<typeof RecipeSnippetSchema>;
+/**
+ * One recipe in the generated reference, keyed by id. Carries the docs
+ * metadata, the validated step plan, and the composed SDK/CLI/cURL examples
+ * (full runnable snippets with captured values threaded between steps), each
+ * split into a folded `setup` preamble + the `main` goal steps.
+ */
+export declare const RecipeReferenceEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    goal: z.ZodString;
+    category: z.ZodString;
+    video: z.ZodString;
+    walkthrough: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        caption: z.ZodString;
+        image: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"sdk">;
+        operationId: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
+        phase: z.ZodEnum<{
+            setup: "setup";
+            main: "main";
+        }>;
+        inputs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            $ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            value: z.ZodUnknown;
+        }, z.core.$strict>]>>;
+        poll: z.ZodOptional<z.ZodObject<{
+            until: z.ZodUnion<readonly [z.ZodObject<{
+                path: z.ZodString;
+                in: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                path: z.ZodString;
+                present: z.ZodLiteral<true>;
+            }, z.core.$strict>]>;
+            failOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                path: z.ZodString;
+                in: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                path: z.ZodString;
+                present: z.ZodLiteral<true>;
+            }, z.core.$strict>]>>;
+            timeoutMs: z.ZodNumber;
+            intervalMs: z.ZodNumber;
+        }, z.core.$strict>>;
+        captures: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"intelligence">;
+        caption: z.ZodString;
+        phase: z.ZodEnum<{
+            setup: "setup";
+            main: "main";
+        }>;
+        gql: z.ZodObject<{
+            query: z.ZodString;
+            variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>;
+        captures: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>], "kind">>;
+    sdk: z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strict>;
+    cli: z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strict>;
+    curl: z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strict>;
+    related: z.ZodOptional<z.ZodObject<{
+        requires: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"recipe">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"state">;
+            explanation: z.ZodString;
+            predicate: z.ZodOptional<z.ZodString>;
+            via: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"recipe">;
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"concept">;
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"tutorial">;
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"resource">;
+                id: z.ZodString;
+            }, z.core.$strict>], "type">>;
+        }, z.core.$strict>], "type">>>;
+        variationOf: z.ZodOptional<z.ZodString>;
+        learnMore: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"concept">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"tutorial">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"resource">;
+            id: z.ZodString;
+        }, z.core.$strict>], "type">>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RecipeReferenceEntry = z.infer<typeof RecipeReferenceEntrySchema>;