@vectros-ai/blueprints 0.5.0 → 0.6.3

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 All notable changes to `@vectros-ai/blueprints` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.6.3 — 2026-07-01
+
+### Added
+
+- **`agentic-sdlc` now declares an `editor` role for the human owner.** `bootstrap`
+  provisions a scoped key for your *agent*, but doesn't join *you* — so a blueprint's
+  context doesn't appear in the data-plane app until your own user is granted access
+  there. The blueprint now ships a reusable `editor` role at **parity with the service
+  key** (`records:r/c/u`, `search:r`, `schemas:r`, `inference:r`, `documents:r/c`,
+  `folders:r/c`; no delete, no control-plane), which `bootstrap` creates in the context.
+  Bind it to your user once to browse and curate the KB in the app:
+  `vectros access grant --principal usr_<your-user-id> --context agentic-sdlc --role editor`
+  (or via the admin app's Access → Contexts → Profiles). The guide and walkthrough
+  document the one-time join, and the package README now documents the top-level
+  `roles` format field (previously undocumented — no bundled blueprint used it).
+
+## 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
 
@@ -106,6 +115,16 @@ The `accessProfile.dataScope` value lists accept a **`null` sentinel** — e.g.
 (owner-less / shared) records. Omitting `null` restricts the key to the listed
 owners only.
 
+A blueprint may also declare top-level **`roles`** — a map of `roleId` → ordered
+scope clauses (each an `allowedActions` list with an optional `dataScope`). Unlike
+`accessProfile` (which scopes the service-principal key `bootstrap` mints), roles
+are reusable, identity-agnostic rules you bind to a principal *after* bootstrap with
+`vectros access grant --principal <p> --role <roleId>`. `bootstrap` provisions the
+declared roles in the context but binds them to no one. The bundled `agentic-sdlc`
+ships an `editor` role for this — join your own user to the context so you can
+browse and curate the knowledge base in the app. Role clauses pass the same
+data-plane scope gate as `accessProfile`.
+
 All of the above are **optional and backward-compatible** — a blueprint that
 omits them parses and provisions exactly as before.
 

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 };