@contractspec/example.video-marketing-clip 2.1.0

package/dist/docs/index.js

@@ -0,0 +1,68 @@
+// @bun
+// src/docs/video-marketing-clip.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-marketing-clip",
+    title: "Video Marketing Clips (example)",
+    summary: "End-to-end example: generate short-form social clips from content briefs using the deterministic video-gen pipeline.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip",
+    tags: ["video", "marketing", "social-clip", "example"],
+    body: `## What this example shows
+
+- Building a \`VideoBrief\` from a \`ContentBrief\` with format, duration, and style settings.
+- Using \`VideoGenerator\` in fully deterministic mode (no LLM) to produce a \`VideoProject\`.
+- Generating video projects for all three social formats: landscape (16:9), square (1:1), and portrait (9:16).
+- Accessing the resulting scene graph, durations, and composition props.
+
+## Key concepts
+
+- **ContentBrief**: The narrative source (title, problems, solutions, CTA) from \`@contractspec/lib.content-gen\`.
+- **VideoBrief**: Wraps ContentBrief with video-specific config (format, duration, narration, style).
+- **VideoGenerator**: Orchestrates scene planning and project assembly. Deterministic by default.
+- **VideoProject**: The output scene graph ready for rendering or preview.
+
+## Notes
+
+- No LLM or voice provider is needed -- the pipeline is fully deterministic.
+- The example does not render to MP4 (that requires Node.js + \`@remotion/renderer\`). It produces the \`VideoProject\` data structure.
+`
+  },
+  {
+    id: "docs.examples.video-marketing-clip.usage",
+    title: "Video Marketing Clips -- Usage",
+    summary: "How to generate marketing video projects from content briefs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip/usage",
+    tags: ["video", "marketing", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { generateMarketingClip } from "@contractspec/example.video-marketing-clip/generate-clip";
+import { productLaunchBrief } from "@contractspec/example.video-marketing-clip/briefs";
+
+// Generate a landscape video project
+const project = await generateMarketingClip(productLaunchBrief, "landscape");
+
+console.log(project.scenes.length);          // number of scenes
+console.log(project.totalDurationInFrames);  // total frames
+console.log(project.format);                 // { type: "landscape", width: 1920, height: 1080 }
+
+// Generate all three format variants
+const landscapes = await generateMarketingClip(productLaunchBrief, "landscape");
+const square = await generateMarketingClip(productLaunchBrief, "square");
+const portrait = await generateMarketingClip(productLaunchBrief, "portrait");
+\`\`\`
+
+## Guardrails
+
+- Keep content briefs concise -- the deterministic planner maps each section to a 2-5 second scene.
+- Target duration defaults to ~17 seconds if not specified. Set \`targetDurationSeconds\` for precise control.
+- The generated \`VideoProject\` is a data structure, not a rendered file. Use \`LocalRenderer\` for MP4 output.
+`
+  }
+];
+registerDocBlocks(blocks);

package/dist/docs/video-marketing-clip.docblock.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/docs/video-marketing-clip.docblock.js

@@ -0,0 +1,68 @@
+// @bun
+// src/docs/video-marketing-clip.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-marketing-clip",
+    title: "Video Marketing Clips (example)",
+    summary: "End-to-end example: generate short-form social clips from content briefs using the deterministic video-gen pipeline.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip",
+    tags: ["video", "marketing", "social-clip", "example"],
+    body: `## What this example shows
+
+- Building a \`VideoBrief\` from a \`ContentBrief\` with format, duration, and style settings.
+- Using \`VideoGenerator\` in fully deterministic mode (no LLM) to produce a \`VideoProject\`.
+- Generating video projects for all three social formats: landscape (16:9), square (1:1), and portrait (9:16).
+- Accessing the resulting scene graph, durations, and composition props.
+
+## Key concepts
+
+- **ContentBrief**: The narrative source (title, problems, solutions, CTA) from \`@contractspec/lib.content-gen\`.
+- **VideoBrief**: Wraps ContentBrief with video-specific config (format, duration, narration, style).
+- **VideoGenerator**: Orchestrates scene planning and project assembly. Deterministic by default.
+- **VideoProject**: The output scene graph ready for rendering or preview.
+
+## Notes
+
+- No LLM or voice provider is needed -- the pipeline is fully deterministic.
+- The example does not render to MP4 (that requires Node.js + \`@remotion/renderer\`). It produces the \`VideoProject\` data structure.
+`
+  },
+  {
+    id: "docs.examples.video-marketing-clip.usage",
+    title: "Video Marketing Clips -- Usage",
+    summary: "How to generate marketing video projects from content briefs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip/usage",
+    tags: ["video", "marketing", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { generateMarketingClip } from "@contractspec/example.video-marketing-clip/generate-clip";
+import { productLaunchBrief } from "@contractspec/example.video-marketing-clip/briefs";
+
+// Generate a landscape video project
+const project = await generateMarketingClip(productLaunchBrief, "landscape");
+
+console.log(project.scenes.length);          // number of scenes
+console.log(project.totalDurationInFrames);  // total frames
+console.log(project.format);                 // { type: "landscape", width: 1920, height: 1080 }
+
+// Generate all three format variants
+const landscapes = await generateMarketingClip(productLaunchBrief, "landscape");
+const square = await generateMarketingClip(productLaunchBrief, "square");
+const portrait = await generateMarketingClip(productLaunchBrief, "portrait");
+\`\`\`
+
+## Guardrails
+
+- Keep content briefs concise -- the deterministic planner maps each section to a 2-5 second scene.
+- Target duration defaults to ~17 seconds if not specified. Set \`targetDurationSeconds\` for precise control.
+- The generated \`VideoProject\` is a data structure, not a rendered file. Use \`LocalRenderer\` for MP4 output.
+`
+  }
+];
+registerDocBlocks(blocks);

package/dist/example.d.ts

@@ -0,0 +1,2 @@
+declare const example: import("@contractspec/lib.contracts-spec").ExampleSpec;
+export default example;

package/dist/example.js

@@ -0,0 +1,34 @@
+// @bun
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts-spec";
+var example = defineExample({
+  meta: {
+    key: "video-marketing-clip",
+    version: "1.0.0",
+    title: "Video Marketing Clips",
+    description: "Generate short-form marketing videos from content briefs using the deterministic video-gen pipeline.",
+    kind: "script",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["video", "marketing", "content-gen", "social-clip"]
+  },
+  docs: {
+    rootDocId: "docs.examples.video-marketing-clip",
+    usageDocId: "docs.examples.video-marketing-clip.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.video-marketing-clip",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/generate-clip.d.ts

@@ -0,0 +1,35 @@
+import type { ContentBrief } from '@contractspec/lib.content-gen/types';
+import type { VideoProject } from '@contractspec/lib.video-gen/types';
+/** Supported social format keys. */
+export type SocialFormat = 'landscape' | 'square' | 'portrait';
+/**
+ * Generate a marketing video project from a content brief.
+ *
+ * This is the main handler demonstrating the deterministic video-gen pipeline:
+ * 1. Wrap the ContentBrief in a VideoBrief with format + duration config
+ * 2. Use VideoGenerator (no LLM) to plan scenes and assemble the project
+ * 3. Return the VideoProject (scene graph ready for rendering)
+ *
+ * @example
+ * ```ts
+ * import { generateMarketingClip } from "@contractspec/example.video-marketing-clip/generate-clip";
+ * import { productLaunchBrief } from "@contractspec/example.video-marketing-clip/briefs";
+ *
+ * const project = await generateMarketingClip(productLaunchBrief, "landscape");
+ * console.log(project.scenes.length); // 5
+ * ```
+ */
+export declare function generateMarketingClip(brief: ContentBrief, format?: SocialFormat, targetDurationSeconds?: number): Promise<VideoProject>;
+/**
+ * Generate video projects for all three social formats from a single brief.
+ *
+ * Returns landscape, square, and portrait variants -- useful for
+ * cross-platform social media campaigns.
+ *
+ * @example
+ * ```ts
+ * const variants = await generateAllFormats(productLaunchBrief, 30);
+ * // variants.landscape, variants.square, variants.portrait
+ * ```
+ */
+export declare function generateAllFormats(brief: ContentBrief, targetDurationSeconds?: number): Promise<Record<SocialFormat, VideoProject>>;

package/dist/generate-clip.js

@@ -0,0 +1,30 @@
+// @bun
+// src/generate-clip.ts
+import { VideoGenerator } from "@contractspec/lib.video-gen/generators";
+import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
+var FORMAT_MAP = {
+  landscape: VIDEO_FORMATS.landscape,
+  square: VIDEO_FORMATS.square,
+  portrait: VIDEO_FORMATS.portrait
+};
+async function generateMarketingClip(brief, format = "landscape", targetDurationSeconds) {
+  const generator = new VideoGenerator({ fps: 30 });
+  const videoBrief = {
+    content: brief,
+    format: FORMAT_MAP[format],
+    targetDurationSeconds
+  };
+  return generator.generate(videoBrief);
+}
+async function generateAllFormats(brief, targetDurationSeconds) {
+  const [landscape, square, portrait] = await Promise.all([
+    generateMarketingClip(brief, "landscape", targetDurationSeconds),
+    generateMarketingClip(brief, "square", targetDurationSeconds),
+    generateMarketingClip(brief, "portrait", targetDurationSeconds)
+  ]);
+  return { landscape, square, portrait };
+}
+export {
+  generateMarketingClip,
+  generateAllFormats
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './briefs';
+export * from './generate-clip';
+export { default as example } from './example';
+import './docs';

package/dist/index.js

@@ -0,0 +1,202 @@
+// @bun
+// src/briefs.ts
+var productLaunchBrief = {
+  title: "Ship APIs 10x Faster with ContractSpec",
+  summary: "ContractSpec generates REST, GraphQL, DB schemas, SDKs, and MCP tools from a single spec definition.",
+  problems: [
+    "Teams rewrite the same API logic across multiple surfaces",
+    "Manual synchronization leads to inconsistent endpoints",
+    "Schema drift between frontend, backend, and documentation"
+  ],
+  solutions: [
+    "One spec, every surface -- define once, generate everything",
+    "Deterministic output -- same spec always produces the same code",
+    "Fully ejectable -- no lock-in, standard TypeScript"
+  ],
+  metrics: [
+    "10x faster API development",
+    "Zero schema drift across surfaces",
+    "18 generated files from 3 contracts"
+  ],
+  audience: {
+    role: "Engineering Lead",
+    industry: "SaaS",
+    painPoints: ["API maintenance burden", "Cross-surface consistency"]
+  },
+  callToAction: "Try ContractSpec today at contractspec.dev"
+};
+var featureAnnouncementBrief = {
+  title: "Now Generating MCP Tools from Your Specs",
+  summary: "ContractSpec v2 adds automatic MCP tool generation -- your contracts now power AI assistants natively.",
+  problems: [
+    "Building MCP tools manually is tedious and error-prone",
+    "AI assistants need structured tool definitions that stay in sync with APIs"
+  ],
+  solutions: [
+    "Automatic MCP tool generation from existing contract specs",
+    "Type-safe tool definitions with Zod schema validation",
+    "Zero additional configuration -- just build"
+  ],
+  audience: {
+    role: "Developer",
+    painPoints: ["MCP integration complexity"]
+  },
+  callToAction: "Upgrade to ContractSpec v2"
+};
+var caseStudyBrief = {
+  title: "How Acme Corp Cut API Dev Time by 80%",
+  summary: "Acme Corp migrated 47 endpoints to ContractSpec and eliminated manual synchronization across 5 surfaces.",
+  problems: [
+    "47 REST endpoints maintained manually across 3 teams",
+    "GraphQL schema constantly out of sync with REST",
+    "SDK updates lagged behind API changes by weeks"
+  ],
+  solutions: [
+    "Migrated to ContractSpec in 2 weeks",
+    "Single source of truth for all 47 endpoints",
+    "Automated SDK and documentation generation"
+  ],
+  metrics: [
+    "80% reduction in API development time",
+    "Zero sync issues since migration",
+    "3 teams now share one spec repository"
+  ],
+  audience: {
+    role: "CTO",
+    industry: "FinTech",
+    painPoints: ["API maintenance costs", "Team coordination"]
+  },
+  callToAction: "Read the full case study at contractspec.dev/customers"
+};
+
+// src/docs/video-marketing-clip.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-marketing-clip",
+    title: "Video Marketing Clips (example)",
+    summary: "End-to-end example: generate short-form social clips from content briefs using the deterministic video-gen pipeline.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip",
+    tags: ["video", "marketing", "social-clip", "example"],
+    body: `## What this example shows
+
+- Building a \`VideoBrief\` from a \`ContentBrief\` with format, duration, and style settings.
+- Using \`VideoGenerator\` in fully deterministic mode (no LLM) to produce a \`VideoProject\`.
+- Generating video projects for all three social formats: landscape (16:9), square (1:1), and portrait (9:16).
+- Accessing the resulting scene graph, durations, and composition props.
+
+## Key concepts
+
+- **ContentBrief**: The narrative source (title, problems, solutions, CTA) from \`@contractspec/lib.content-gen\`.
+- **VideoBrief**: Wraps ContentBrief with video-specific config (format, duration, narration, style).
+- **VideoGenerator**: Orchestrates scene planning and project assembly. Deterministic by default.
+- **VideoProject**: The output scene graph ready for rendering or preview.
+
+## Notes
+
+- No LLM or voice provider is needed -- the pipeline is fully deterministic.
+- The example does not render to MP4 (that requires Node.js + \`@remotion/renderer\`). It produces the \`VideoProject\` data structure.
+`
+  },
+  {
+    id: "docs.examples.video-marketing-clip.usage",
+    title: "Video Marketing Clips -- Usage",
+    summary: "How to generate marketing video projects from content briefs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip/usage",
+    tags: ["video", "marketing", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { generateMarketingClip } from "@contractspec/example.video-marketing-clip/generate-clip";
+import { productLaunchBrief } from "@contractspec/example.video-marketing-clip/briefs";
+
+// Generate a landscape video project
+const project = await generateMarketingClip(productLaunchBrief, "landscape");
+
+console.log(project.scenes.length);          // number of scenes
+console.log(project.totalDurationInFrames);  // total frames
+console.log(project.format);                 // { type: "landscape", width: 1920, height: 1080 }
+
+// Generate all three format variants
+const landscapes = await generateMarketingClip(productLaunchBrief, "landscape");
+const square = await generateMarketingClip(productLaunchBrief, "square");
+const portrait = await generateMarketingClip(productLaunchBrief, "portrait");
+\`\`\`
+
+## Guardrails
+
+- Keep content briefs concise -- the deterministic planner maps each section to a 2-5 second scene.
+- Target duration defaults to ~17 seconds if not specified. Set \`targetDurationSeconds\` for precise control.
+- The generated \`VideoProject\` is a data structure, not a rendered file. Use \`LocalRenderer\` for MP4 output.
+`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts-spec";
+var example = defineExample({
+  meta: {
+    key: "video-marketing-clip",
+    version: "1.0.0",
+    title: "Video Marketing Clips",
+    description: "Generate short-form marketing videos from content briefs using the deterministic video-gen pipeline.",
+    kind: "script",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["video", "marketing", "content-gen", "social-clip"]
+  },
+  docs: {
+    rootDocId: "docs.examples.video-marketing-clip",
+    usageDocId: "docs.examples.video-marketing-clip.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.video-marketing-clip",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+
+// src/generate-clip.ts
+import { VideoGenerator } from "@contractspec/lib.video-gen/generators";
+import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
+var FORMAT_MAP = {
+  landscape: VIDEO_FORMATS.landscape,
+  square: VIDEO_FORMATS.square,
+  portrait: VIDEO_FORMATS.portrait
+};
+async function generateMarketingClip(brief, format = "landscape", targetDurationSeconds) {
+  const generator = new VideoGenerator({ fps: 30 });
+  const videoBrief = {
+    content: brief,
+    format: FORMAT_MAP[format],
+    targetDurationSeconds
+  };
+  return generator.generate(videoBrief);
+}
+async function generateAllFormats(brief, targetDurationSeconds) {
+  const [landscape, square, portrait] = await Promise.all([
+    generateMarketingClip(brief, "landscape", targetDurationSeconds),
+    generateMarketingClip(brief, "square", targetDurationSeconds),
+    generateMarketingClip(brief, "portrait", targetDurationSeconds)
+  ]);
+  return { landscape, square, portrait };
+}
+export {
+  productLaunchBrief,
+  generateMarketingClip,
+  generateAllFormats,
+  featureAnnouncementBrief,
+  example_default as example,
+  caseStudyBrief
+};

package/dist/node/briefs.js

@@ -0,0 +1,74 @@
+// src/briefs.ts
+var productLaunchBrief = {
+  title: "Ship APIs 10x Faster with ContractSpec",
+  summary: "ContractSpec generates REST, GraphQL, DB schemas, SDKs, and MCP tools from a single spec definition.",
+  problems: [
+    "Teams rewrite the same API logic across multiple surfaces",
+    "Manual synchronization leads to inconsistent endpoints",
+    "Schema drift between frontend, backend, and documentation"
+  ],
+  solutions: [
+    "One spec, every surface -- define once, generate everything",
+    "Deterministic output -- same spec always produces the same code",
+    "Fully ejectable -- no lock-in, standard TypeScript"
+  ],
+  metrics: [
+    "10x faster API development",
+    "Zero schema drift across surfaces",
+    "18 generated files from 3 contracts"
+  ],
+  audience: {
+    role: "Engineering Lead",
+    industry: "SaaS",
+    painPoints: ["API maintenance burden", "Cross-surface consistency"]
+  },
+  callToAction: "Try ContractSpec today at contractspec.dev"
+};
+var featureAnnouncementBrief = {
+  title: "Now Generating MCP Tools from Your Specs",
+  summary: "ContractSpec v2 adds automatic MCP tool generation -- your contracts now power AI assistants natively.",
+  problems: [
+    "Building MCP tools manually is tedious and error-prone",
+    "AI assistants need structured tool definitions that stay in sync with APIs"
+  ],
+  solutions: [
+    "Automatic MCP tool generation from existing contract specs",
+    "Type-safe tool definitions with Zod schema validation",
+    "Zero additional configuration -- just build"
+  ],
+  audience: {
+    role: "Developer",
+    painPoints: ["MCP integration complexity"]
+  },
+  callToAction: "Upgrade to ContractSpec v2"
+};
+var caseStudyBrief = {
+  title: "How Acme Corp Cut API Dev Time by 80%",
+  summary: "Acme Corp migrated 47 endpoints to ContractSpec and eliminated manual synchronization across 5 surfaces.",
+  problems: [
+    "47 REST endpoints maintained manually across 3 teams",
+    "GraphQL schema constantly out of sync with REST",
+    "SDK updates lagged behind API changes by weeks"
+  ],
+  solutions: [
+    "Migrated to ContractSpec in 2 weeks",
+    "Single source of truth for all 47 endpoints",
+    "Automated SDK and documentation generation"
+  ],
+  metrics: [
+    "80% reduction in API development time",
+    "Zero sync issues since migration",
+    "3 teams now share one spec repository"
+  ],
+  audience: {
+    role: "CTO",
+    industry: "FinTech",
+    painPoints: ["API maintenance costs", "Team coordination"]
+  },
+  callToAction: "Read the full case study at contractspec.dev/customers"
+};
+export {
+  productLaunchBrief,
+  featureAnnouncementBrief,
+  caseStudyBrief
+};

package/dist/node/docs/index.js

@@ -0,0 +1,67 @@
+// src/docs/video-marketing-clip.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-marketing-clip",
+    title: "Video Marketing Clips (example)",
+    summary: "End-to-end example: generate short-form social clips from content briefs using the deterministic video-gen pipeline.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip",
+    tags: ["video", "marketing", "social-clip", "example"],
+    body: `## What this example shows
+
+- Building a \`VideoBrief\` from a \`ContentBrief\` with format, duration, and style settings.
+- Using \`VideoGenerator\` in fully deterministic mode (no LLM) to produce a \`VideoProject\`.
+- Generating video projects for all three social formats: landscape (16:9), square (1:1), and portrait (9:16).
+- Accessing the resulting scene graph, durations, and composition props.
+
+## Key concepts
+
+- **ContentBrief**: The narrative source (title, problems, solutions, CTA) from \`@contractspec/lib.content-gen\`.
+- **VideoBrief**: Wraps ContentBrief with video-specific config (format, duration, narration, style).
+- **VideoGenerator**: Orchestrates scene planning and project assembly. Deterministic by default.
+- **VideoProject**: The output scene graph ready for rendering or preview.
+
+## Notes
+
+- No LLM or voice provider is needed -- the pipeline is fully deterministic.
+- The example does not render to MP4 (that requires Node.js + \`@remotion/renderer\`). It produces the \`VideoProject\` data structure.
+`
+  },
+  {
+    id: "docs.examples.video-marketing-clip.usage",
+    title: "Video Marketing Clips -- Usage",
+    summary: "How to generate marketing video projects from content briefs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip/usage",
+    tags: ["video", "marketing", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { generateMarketingClip } from "@contractspec/example.video-marketing-clip/generate-clip";
+import { productLaunchBrief } from "@contractspec/example.video-marketing-clip/briefs";
+
+// Generate a landscape video project
+const project = await generateMarketingClip(productLaunchBrief, "landscape");
+
+console.log(project.scenes.length);          // number of scenes
+console.log(project.totalDurationInFrames);  // total frames
+console.log(project.format);                 // { type: "landscape", width: 1920, height: 1080 }
+
+// Generate all three format variants
+const landscapes = await generateMarketingClip(productLaunchBrief, "landscape");
+const square = await generateMarketingClip(productLaunchBrief, "square");
+const portrait = await generateMarketingClip(productLaunchBrief, "portrait");
+\`\`\`
+
+## Guardrails
+
+- Keep content briefs concise -- the deterministic planner maps each section to a 2-5 second scene.
+- Target duration defaults to ~17 seconds if not specified. Set \`targetDurationSeconds\` for precise control.
+- The generated \`VideoProject\` is a data structure, not a rendered file. Use \`LocalRenderer\` for MP4 output.
+`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/docs/video-marketing-clip.docblock.js

@@ -0,0 +1,67 @@
+// src/docs/video-marketing-clip.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var blocks = [
+  {
+    id: "docs.examples.video-marketing-clip",
+    title: "Video Marketing Clips (example)",
+    summary: "End-to-end example: generate short-form social clips from content briefs using the deterministic video-gen pipeline.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip",
+    tags: ["video", "marketing", "social-clip", "example"],
+    body: `## What this example shows
+
+- Building a \`VideoBrief\` from a \`ContentBrief\` with format, duration, and style settings.
+- Using \`VideoGenerator\` in fully deterministic mode (no LLM) to produce a \`VideoProject\`.
+- Generating video projects for all three social formats: landscape (16:9), square (1:1), and portrait (9:16).
+- Accessing the resulting scene graph, durations, and composition props.
+
+## Key concepts
+
+- **ContentBrief**: The narrative source (title, problems, solutions, CTA) from \`@contractspec/lib.content-gen\`.
+- **VideoBrief**: Wraps ContentBrief with video-specific config (format, duration, narration, style).
+- **VideoGenerator**: Orchestrates scene planning and project assembly. Deterministic by default.
+- **VideoProject**: The output scene graph ready for rendering or preview.
+
+## Notes
+
+- No LLM or voice provider is needed -- the pipeline is fully deterministic.
+- The example does not render to MP4 (that requires Node.js + \`@remotion/renderer\`). It produces the \`VideoProject\` data structure.
+`
+  },
+  {
+    id: "docs.examples.video-marketing-clip.usage",
+    title: "Video Marketing Clips -- Usage",
+    summary: "How to generate marketing video projects from content briefs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/video-marketing-clip/usage",
+    tags: ["video", "marketing", "usage"],
+    body: `## Usage
+
+\`\`\`ts
+import { generateMarketingClip } from "@contractspec/example.video-marketing-clip/generate-clip";
+import { productLaunchBrief } from "@contractspec/example.video-marketing-clip/briefs";
+
+// Generate a landscape video project
+const project = await generateMarketingClip(productLaunchBrief, "landscape");
+
+console.log(project.scenes.length);          // number of scenes
+console.log(project.totalDurationInFrames);  // total frames
+console.log(project.format);                 // { type: "landscape", width: 1920, height: 1080 }
+
+// Generate all three format variants
+const landscapes = await generateMarketingClip(productLaunchBrief, "landscape");
+const square = await generateMarketingClip(productLaunchBrief, "square");
+const portrait = await generateMarketingClip(productLaunchBrief, "portrait");
+\`\`\`
+
+## Guardrails
+
+- Keep content briefs concise -- the deterministic planner maps each section to a 2-5 second scene.
+- Target duration defaults to ~17 seconds if not specified. Set \`targetDurationSeconds\` for precise control.
+- The generated \`VideoProject\` is a data structure, not a rendered file. Use \`LocalRenderer\` for MP4 output.
+`
+  }
+];
+registerDocBlocks(blocks);