@vectros-ai/blueprints 0.5.0 → 0.6.2

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 All notable changes to `@vectros-ai/blueprints` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.6.2 — 2026-06-29
+
+### Changed
+
+- **`agentic-sdlc` ingest guidance corrected for explicit upsert.** The guide and the
+  ingest-agent prompt now describe syncing accurately: re-ingesting an unchanged item
+  returns it as-is (`created: false`), and propagating **edited** source requires
+  `upsert: true` — a plain re-create returns the existing item unchanged rather than
+  applying the edit. Pick stable `externalId`s and re-ingest with `upsert` to keep the
+  knowledge base in sync; a from-scratch rebuild into an empty context is unaffected.
+
+## 0.6.1 — 2026-06-28
+
+### Added
+
+- New bundled blueprint **`agentic-sdlc`** — a whole-SDLC system of
+  record for an AI development team, organized by **content vs structure**. Nine
+  schemas: ADRs (`decision`), `design`/specs, `reference`, `runbook`, and
+  `postmortem` bind the **document** surface (the markdown body is the artifact);
+  `control`, `convention`, `gotcha`, and a glossary `term` are **records** (the
+  typed fields are the artifact). They form a **cross-surface knowledge graph** —
+  records reference documents (`control` → the `runbook` that verifies it;
+  `convention`/`term` → the `decision` behind them) and documents reference
+  documents (a `design` → its `decision`, a `runbook` → the `postmortem` it was
+  born from, an ADR → the one it supersedes). Shows hybrid search + grounded
+  `rag_ask` over document bodies, range/sort on every artifact's date, a
+  governance `control` that carries its evidence, a `convention` with distinct
+  rule/why/howToApply fields, and a glossary `term` with a `unique` lookup. Ships
+  without bundled seeds (the cross-surface graph is populated by the ingest agent).
+- Usage guide (`guides/agentic-sdlc.md`) and drop-in agent orientation prompt
+  (`prompts/agentic-sdlc-agent.md`) shipped with the package.
+
+## 0.6.0 — 2026-06-28
+
+### Added
+
+- **Document seeds.** A seed entry now declares a **surface**: `surface: record`
+  (a structured record — the existing behavior) or `surface: document` (a
+  text-ingested document carrying a `title` and `text`, with optional structured
+  `fields`). A blueprint can now pre-populate documents, not just records, and
+  model a **cross-surface graph** — a record's `reference` can target a seeded
+  document by `externalId`, and vice versa. A seed's surface is validated against
+  the bound schema's `allowedSurfaces`.
+
+### Changed
+
+- **Breaking (format):** every seed entry must now declare `surface`. Existing
+  record seeds add `surface: record`. The discriminator is explicit by design — a
+  document seed's first-class `title`/`text` are distinct from a record's
+  `fields`, so the two shapes are validated separately.
+
 ## 0.5.0 — 2026-06-20
 
 Initial public release of the Vectros blueprints library.

package/README.md

@@ -1,5 +1,8 @@
 # @vectros-ai/blueprints
 
+[![npm](https://img.shields.io/npm/v/@vectros-ai/blueprints)](https://www.npmjs.com/package/@vectros-ai/blueprints)
+[![license](https://img.shields.io/npm/l/@vectros-ai/blueprints)](https://www.apache.org/licenses/LICENSE-2.0)
+
 The Vectros **blueprint** format + the curated bundled library.
 
 A **blueprint** is a versioned, reviewed bundle for one use case: a schema
@@ -39,8 +42,14 @@ already-parsed object. Both throw `BlueprintValidationError` on a bad shape.
   `MCP — <name>` when the blueprint omits `contextName`.
 - `BUNDLED_BLUEPRINTS` / `BLUEPRINT_NAMES` / `getBlueprint(name)` — the
   curated library: `task-management` (the minimal authoring exemplar),
-  `coding-agent-memory`, `second-brain`, and `clinical-intake` (the flagship
-  use-case blueprints).
+  `coding-agent-memory`, `agentic-sdlc` (a whole-SDLC system of
+  record for an AI dev team: nine schemas split by content vs structure — ADRs,
+  designs, references, runbooks, and post-mortems as **documents**; controls,
+  conventions, gotchas, and a glossary as **records** — linked into a
+  **cross-surface** knowledge graph, with hybrid search + grounded `rag_ask`; see
+  [`guides/agentic-sdlc.md`](guides/agentic-sdlc.md) and the drop-in agent prompt
+  [`prompts/agentic-sdlc-agent.md`](prompts/agentic-sdlc-agent.md)),
+  `second-brain`, and `clinical-intake` (the PHI/sensitive-field exemplar).
 
 ## The format, field by field
 

package/dist/index.d.mts

@@ -751,19 +751,89 @@ declare const IdentitiesDeclSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     displayName?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
 }>>;
-declare const BlueprintSeedRecordSchema: z.ZodObject<{
+declare const RecordSeedSchema: z.ZodObject<{
+    /** The record payload, validated against the bound schema. */
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     typeName: z.ZodString;
     externalId: z.ZodString;
-    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    surface: z.ZodLiteral<"record">;
 }, "strict", z.ZodTypeAny, {
     typeName: string;
     fields: Record<string, unknown>;
     externalId: string;
+    surface: "record";
 }, {
     typeName: string;
     fields: Record<string, unknown>;
     externalId: string;
+    surface: "record";
 }>;
+declare const DocumentSeedSchema: z.ZodObject<{
+    /** Human-readable document title — REQUIRED by the text-ingest path. */
+    title: z.ZodString;
+    /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+    text: z.ZodString;
+    /** Optional structured payload bound to the schema (the document's `fields`). */
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    typeName: z.ZodString;
+    externalId: z.ZodString;
+    surface: z.ZodLiteral<"document">;
+}, "strict", z.ZodTypeAny, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}>;
+declare const BlueprintSeedRecordSchema: z.ZodDiscriminatedUnion<"surface", [z.ZodObject<{
+    /** The record payload, validated against the bound schema. */
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    typeName: z.ZodString;
+    externalId: z.ZodString;
+    surface: z.ZodLiteral<"record">;
+}, "strict", z.ZodTypeAny, {
+    typeName: string;
+    fields: Record<string, unknown>;
+    externalId: string;
+    surface: "record";
+}, {
+    typeName: string;
+    fields: Record<string, unknown>;
+    externalId: string;
+    surface: "record";
+}>, z.ZodObject<{
+    /** Human-readable document title — REQUIRED by the text-ingest path. */
+    title: z.ZodString;
+    /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+    text: z.ZodString;
+    /** Optional structured payload bound to the schema (the document's `fields`). */
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    typeName: z.ZodString;
+    externalId: z.ZodString;
+    surface: z.ZodLiteral<"document">;
+}, "strict", z.ZodTypeAny, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}>]>;
 declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
     /** Stable blueprint id (the `--blueprint <name>` selector + idempotency key). */
     name: z.ZodString;
@@ -1167,19 +1237,47 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         displayName: string;
         externalId: string;
     }>;
-    seed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    seed: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"surface", [z.ZodObject<{
+        /** The record payload, validated against the bound schema. */
+        fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         typeName: z.ZodString;
         externalId: z.ZodString;
-        fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        surface: z.ZodLiteral<"record">;
     }, "strict", z.ZodTypeAny, {
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
+        surface: "record";
     }, {
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }>, "many">>;
+        surface: "record";
+    }>, z.ZodObject<{
+        /** Human-readable document title — REQUIRED by the text-ingest path. */
+        title: z.ZodString;
+        /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+        text: z.ZodString;
+        /** Optional structured payload bound to the schema (the document's `fields`). */
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        typeName: z.ZodString;
+        externalId: z.ZodString;
+        surface: z.ZodLiteral<"document">;
+    }, "strict", z.ZodTypeAny, {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    }, {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    }>]>, "many">>;
     /** Optional multi-clause roles, bound to principals via `access grant --role`. */
     roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
         allowedActions: z.ZodArray<z.ZodString, "many">;
@@ -1280,11 +1378,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         externalId: string;
     };
     contextName?: string | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1367,11 +1473,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         orgId?: string | undefined;
         clientId?: string | undefined;
     }[] | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1454,11 +1568,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         externalId: string;
     };
     contextName?: string | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1541,11 +1663,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         orgId?: string | undefined;
         clientId?: string | undefined;
     }[] | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1560,7 +1690,14 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
 type Blueprint = z.infer<typeof BlueprintSchema>;
 type BlueprintFieldDef = z.infer<typeof BlueprintFieldDefSchema>;
 type BlueprintSchemaDef = z.infer<typeof BlueprintSchemaSchema>;
-type BlueprintSeedRecord = z.infer<typeof BlueprintSeedRecordSchema>;
+/** A single seed entry — a record seed OR a document seed (discriminated on `surface`). */
+type BlueprintSeed = z.infer<typeof BlueprintSeedRecordSchema>;
+/** The record-surface seed variant (`surface: 'record'`; the default). */
+type BlueprintRecordSeed = z.infer<typeof RecordSeedSchema>;
+/** The document-surface seed variant (`surface: 'document'`; carries `title` + `text`). */
+type BlueprintDocumentSeed = z.infer<typeof DocumentSeedSchema>;
+/** @deprecated The element type of `seed[]`, now a union — use {@link BlueprintSeed}. */
+type BlueprintSeedRecord = BlueprintSeed;
 type BlueprintValidationRules = z.infer<typeof ValidationRulesSchema>;
 type BlueprintRenderHints = z.infer<typeof RenderHintsSchema>;
 type BlueprintLookupField = z.infer<typeof BlueprintLookupFieldSchema>;
@@ -1769,4 +1906,4 @@ declare const BLUEPRINT_NAMES: readonly string[];
 /** Look up a bundled blueprint by name; `undefined` if none matches. */
 declare function getBlueprint(name: string): Blueprint | undefined;
 
-export { BLUEPRINT_NAMES, BUNDLED_BLUEPRINTS, type Blueprint, type BlueprintFieldDef, BlueprintIdentityError, BlueprintInputError, type BlueprintIssue, type BlueprintLookupField, type BlueprintRenderHints, type BlueprintRoleClause, type BlueprintRoles, BlueprintSchema, type BlueprintSchemaDef, type BlueprintSeedRecord, BlueprintValidationError, type BlueprintValidationRules, type IdentitiesDecl, type IdentityDecl, type IdentityResolver, type InputDecl, type InputScalar, type InputsDecl, InputsDeclSchema, collectIdentityReferences, contextNameOf, deriveSuffix, getBlueprint, parseBlueprint, parseBlueprintJson, resolveBlueprintIdentities, resolveBlueprintInputs };
+export { BLUEPRINT_NAMES, BUNDLED_BLUEPRINTS, type Blueprint, type BlueprintDocumentSeed, type BlueprintFieldDef, BlueprintIdentityError, BlueprintInputError, type BlueprintIssue, type BlueprintLookupField, type BlueprintRecordSeed, type BlueprintRenderHints, type BlueprintRoleClause, type BlueprintRoles, BlueprintSchema, type BlueprintSchemaDef, type BlueprintSeed, type BlueprintSeedRecord, BlueprintValidationError, type BlueprintValidationRules, type IdentitiesDecl, type IdentityDecl, type IdentityResolver, type InputDecl, type InputScalar, type InputsDecl, InputsDeclSchema, collectIdentityReferences, contextNameOf, deriveSuffix, getBlueprint, parseBlueprint, parseBlueprintJson, resolveBlueprintIdentities, resolveBlueprintInputs };

package/dist/index.d.ts

@@ -751,19 +751,89 @@ declare const IdentitiesDeclSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     displayName?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
 }>>;
-declare const BlueprintSeedRecordSchema: z.ZodObject<{
+declare const RecordSeedSchema: z.ZodObject<{
+    /** The record payload, validated against the bound schema. */
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     typeName: z.ZodString;
     externalId: z.ZodString;
-    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    surface: z.ZodLiteral<"record">;
 }, "strict", z.ZodTypeAny, {
     typeName: string;
     fields: Record<string, unknown>;
     externalId: string;
+    surface: "record";
 }, {
     typeName: string;
     fields: Record<string, unknown>;
     externalId: string;
+    surface: "record";
 }>;
+declare const DocumentSeedSchema: z.ZodObject<{
+    /** Human-readable document title — REQUIRED by the text-ingest path. */
+    title: z.ZodString;
+    /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+    text: z.ZodString;
+    /** Optional structured payload bound to the schema (the document's `fields`). */
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    typeName: z.ZodString;
+    externalId: z.ZodString;
+    surface: z.ZodLiteral<"document">;
+}, "strict", z.ZodTypeAny, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}>;
+declare const BlueprintSeedRecordSchema: z.ZodDiscriminatedUnion<"surface", [z.ZodObject<{
+    /** The record payload, validated against the bound schema. */
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    typeName: z.ZodString;
+    externalId: z.ZodString;
+    surface: z.ZodLiteral<"record">;
+}, "strict", z.ZodTypeAny, {
+    typeName: string;
+    fields: Record<string, unknown>;
+    externalId: string;
+    surface: "record";
+}, {
+    typeName: string;
+    fields: Record<string, unknown>;
+    externalId: string;
+    surface: "record";
+}>, z.ZodObject<{
+    /** Human-readable document title — REQUIRED by the text-ingest path. */
+    title: z.ZodString;
+    /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+    text: z.ZodString;
+    /** Optional structured payload bound to the schema (the document's `fields`). */
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    typeName: z.ZodString;
+    externalId: z.ZodString;
+    surface: z.ZodLiteral<"document">;
+}, "strict", z.ZodTypeAny, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}, {
+    typeName: string;
+    text: string;
+    externalId: string;
+    surface: "document";
+    title: string;
+    fields?: Record<string, unknown> | undefined;
+}>]>;
 declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
     /** Stable blueprint id (the `--blueprint <name>` selector + idempotency key). */
     name: z.ZodString;
@@ -1167,19 +1237,47 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         displayName: string;
         externalId: string;
     }>;
-    seed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    seed: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"surface", [z.ZodObject<{
+        /** The record payload, validated against the bound schema. */
+        fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         typeName: z.ZodString;
         externalId: z.ZodString;
-        fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        surface: z.ZodLiteral<"record">;
     }, "strict", z.ZodTypeAny, {
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
+        surface: "record";
     }, {
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }>, "many">>;
+        surface: "record";
+    }>, z.ZodObject<{
+        /** Human-readable document title — REQUIRED by the text-ingest path. */
+        title: z.ZodString;
+        /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+        text: z.ZodString;
+        /** Optional structured payload bound to the schema (the document's `fields`). */
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        typeName: z.ZodString;
+        externalId: z.ZodString;
+        surface: z.ZodLiteral<"document">;
+    }, "strict", z.ZodTypeAny, {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    }, {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    }>]>, "many">>;
     /** Optional multi-clause roles, bound to principals via `access grant --role`. */
     roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
         allowedActions: z.ZodArray<z.ZodString, "many">;
@@ -1280,11 +1378,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         externalId: string;
     };
     contextName?: string | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1367,11 +1473,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         orgId?: string | undefined;
         clientId?: string | undefined;
     }[] | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1454,11 +1568,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         externalId: string;
     };
     contextName?: string | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1541,11 +1663,19 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
         orgId?: string | undefined;
         clientId?: string | undefined;
     }[] | undefined;
-    seed?: {
+    seed?: ({
         typeName: string;
         fields: Record<string, unknown>;
         externalId: string;
-    }[] | undefined;
+        surface: "record";
+    } | {
+        typeName: string;
+        text: string;
+        externalId: string;
+        surface: "document";
+        title: string;
+        fields?: Record<string, unknown> | undefined;
+    })[] | undefined;
     roles?: Record<string, {
         allowedActions: string[];
         dataScope?: Record<string, (string | null)[]> | undefined;
@@ -1560,7 +1690,14 @@ declare const BlueprintSchema: z.ZodEffects<z.ZodObject<{
 type Blueprint = z.infer<typeof BlueprintSchema>;
 type BlueprintFieldDef = z.infer<typeof BlueprintFieldDefSchema>;
 type BlueprintSchemaDef = z.infer<typeof BlueprintSchemaSchema>;
-type BlueprintSeedRecord = z.infer<typeof BlueprintSeedRecordSchema>;
+/** A single seed entry — a record seed OR a document seed (discriminated on `surface`). */
+type BlueprintSeed = z.infer<typeof BlueprintSeedRecordSchema>;
+/** The record-surface seed variant (`surface: 'record'`; the default). */
+type BlueprintRecordSeed = z.infer<typeof RecordSeedSchema>;
+/** The document-surface seed variant (`surface: 'document'`; carries `title` + `text`). */
+type BlueprintDocumentSeed = z.infer<typeof DocumentSeedSchema>;
+/** @deprecated The element type of `seed[]`, now a union — use {@link BlueprintSeed}. */
+type BlueprintSeedRecord = BlueprintSeed;
 type BlueprintValidationRules = z.infer<typeof ValidationRulesSchema>;
 type BlueprintRenderHints = z.infer<typeof RenderHintsSchema>;
 type BlueprintLookupField = z.infer<typeof BlueprintLookupFieldSchema>;
@@ -1769,4 +1906,4 @@ declare const BLUEPRINT_NAMES: readonly string[];
 /** Look up a bundled blueprint by name; `undefined` if none matches. */
 declare function getBlueprint(name: string): Blueprint | undefined;
 
-export { BLUEPRINT_NAMES, BUNDLED_BLUEPRINTS, type Blueprint, type BlueprintFieldDef, BlueprintIdentityError, BlueprintInputError, type BlueprintIssue, type BlueprintLookupField, type BlueprintRenderHints, type BlueprintRoleClause, type BlueprintRoles, BlueprintSchema, type BlueprintSchemaDef, type BlueprintSeedRecord, BlueprintValidationError, type BlueprintValidationRules, type IdentitiesDecl, type IdentityDecl, type IdentityResolver, type InputDecl, type InputScalar, type InputsDecl, InputsDeclSchema, collectIdentityReferences, contextNameOf, deriveSuffix, getBlueprint, parseBlueprint, parseBlueprintJson, resolveBlueprintIdentities, resolveBlueprintInputs };
+export { BLUEPRINT_NAMES, BUNDLED_BLUEPRINTS, type Blueprint, type BlueprintDocumentSeed, type BlueprintFieldDef, BlueprintIdentityError, BlueprintInputError, type BlueprintIssue, type BlueprintLookupField, type BlueprintRecordSeed, type BlueprintRenderHints, type BlueprintRoleClause, type BlueprintRoles, BlueprintSchema, type BlueprintSchemaDef, type BlueprintSeed, type BlueprintSeedRecord, BlueprintValidationError, type BlueprintValidationRules, type IdentitiesDecl, type IdentityDecl, type IdentityResolver, type InputDecl, type InputScalar, type InputsDecl, InputsDeclSchema, collectIdentityReferences, contextNameOf, deriveSuffix, getBlueprint, parseBlueprint, parseBlueprintJson, resolveBlueprintIdentities, resolveBlueprintInputs };