@contractspec/bundle.library 3.7.6 → 3.8.2

package/src/components/docs/guides/GuidesIndexPage.tsx

@@ -1,112 +1,122 @@
 import { CodeBlock } from '@contractspec/lib.design-system';
 import Link from '@contractspec/lib.ui-link';
-import { ArrowRight, BookOpen, CheckCircle2 } from 'lucide-react';
+import { ArrowRight, CheckCircle2, GitBranch } from 'lucide-react';
 
 const guides = [
-  {
-    title: 'Contract types overview',
-    description:
-      'Learn about the different contract types and when to use each one.',
-    href: '/docs/guides/contract-types',
-    time: '15 min',
-  },
-  {
-    title: 'Next.js: one endpoint',
-    description:
-      'Add ContractSpec to an existing Next.js app by wiring one operation end-to-end.',
-    href: '/docs/guides/nextjs-one-endpoint',
-    time: '25 min',
-  },
-  {
-    title: 'Import existing codebases',
-    description:
-      'Convert your existing API endpoints into ContractSpec contracts for fast onboarding.',
-    href: '/docs/guides/import-existing-codebases',
-    time: '20 min',
-  },
-  {
-    title: 'Spec-driven validation + typing',
-    description:
-      'Define operations with SchemaModel, generate types, and enforce validation without rewrites.',
-    href: '/docs/guides/spec-validation-and-typing',
-    time: '20 min',
-  },
-  {
-    title: 'Generate docs + client schemas',
-    description:
-      'Export docs and OpenAPI for client SDKs and tooling from your specs.',
-    href: '/docs/guides/generate-docs-clients-schemas',
-    time: '20 min',
-  },
-  {
-    title: 'Docs pipeline',
-    description:
-      'Wire generated docs into a reference site with a chunked index.',
-    href: '/docs/guides/docs-generation-pipeline',
-    time: '20 min',
-  },
-  {
-    title: 'CI gating with deterministic diffs',
-    description:
-      'Add ContractSpec CI checks to gate breaking changes and drift.',
-    href: '/docs/guides/ci-contract-diff-gating',
-    time: '15 min',
-  },
+	{
+		title: 'Adopt one endpoint in Next.js',
+		description:
+			'Start inside a live app with one operation, one generated surface, and one clearly bounded change.',
+		href: '/docs/guides/nextjs-one-endpoint',
+		time: '25 min',
+	},
+	{
+		title: 'Import an existing codebase',
+		description:
+			'Stabilize what already exists instead of treating adoption as a rewrite project.',
+		href: '/docs/guides/import-existing-codebases',
+		time: '20 min',
+	},
+	{
+		title: 'Validation and typing',
+		description:
+			'Keep runtime validation and TypeScript behavior aligned from the same source definitions.',
+		href: '/docs/guides/spec-validation-and-typing',
+		time: '20 min',
+	},
+	{
+		title: 'Generate docs and clients',
+		description:
+			'Publish stable docs, schemas, and client-facing artifacts from the contract layer.',
+		href: '/docs/guides/generate-docs-clients-schemas',
+		time: '20 min',
+	},
+	{
+		title: 'Docs pipeline',
+		description:
+			'Feed generated reference material into the docs site without confusing ownership.',
+		href: '/docs/guides/docs-generation-pipeline',
+		time: '20 min',
+	},
+	{
+		title: 'CI diff gating',
+		description:
+			'Use deterministic checks to catch drift and risky changes before they ship.',
+		href: '/docs/guides/ci-contract-diff-gating',
+		time: '15 min',
+	},
 ];
 
 export function GuidesIndexPage() {
-  return (
-    <div className="space-y-10">
-      <div className="space-y-3">
-        <h1 className="text-4xl font-bold">Guides</h1>
-        <p className="text-muted-foreground text-lg">
-          Hands-on guides with commands, expected output, and CI-verified
-          example packages.
-        </p>
-      </div>
+	return (
+		<div className="space-y-10">
+			<div className="space-y-3">
+				<p className="editorial-kicker">Build</p>
+				<h1 className="font-serif text-4xl tracking-[-0.04em] md:text-5xl">
+					Adoption guides for teams that want to keep their code.
+				</h1>
+				<p className="max-w-3xl text-lg text-muted-foreground leading-8">
+					These guides assume you are introducing ContractSpec into a real code
+					base. Start with a narrow surface, verify the generated outputs, and
+					expand only after the contract loop feels trustworthy.
+				</p>
+			</div>
 
-      <div className="grid gap-4 md:grid-cols-2">
-        {guides.map((guide) => (
-          <Link
-            key={guide.href}
-            href={guide.href}
-            className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"
-          >
-            <div className="flex items-center justify-between">
-              <h2 className="text-xl font-semibold transition-colors group-hover:text-violet-400">
-                {guide.title}
-              </h2>
-              <ArrowRight className="text-violet-400" size={18} />
-            </div>
-            <p className="text-muted-foreground text-sm">{guide.description}</p>
-            <div className="text-muted-foreground flex items-center gap-2 text-xs">
-              <CheckCircle2 size={14} />
-              <span>Target time: {guide.time}</span>
-            </div>
-          </Link>
-        ))}
-      </div>
+			<div className="grid gap-4 md:grid-cols-2">
+				{guides.map((guide) => (
+					<Link key={guide.href} href={guide.href} className="editorial-panel">
+						<div className="flex items-start justify-between gap-4">
+							<div>
+								<h2 className="font-semibold text-xl">{guide.title}</h2>
+								<p className="mt-2 text-muted-foreground text-sm leading-7">
+									{guide.description}
+								</p>
+							</div>
+							<ArrowRight className="mt-1 shrink-0" size={18} />
+						</div>
+						<div className="mt-4 flex items-center gap-2 text-muted-foreground text-xs">
+							<CheckCircle2 size={14} />
+							<span>Target time: {guide.time}</span>
+						</div>
+					</Link>
+				))}
+			</div>
 
-      <div className="card-subtle space-y-4 p-6">
-        <div className="flex items-center gap-2 text-sm font-semibold tracking-[0.2em] text-violet-400 uppercase">
-          <BookOpen size={16} />
-          How to use the guides
-        </div>
-        <ul className="text-muted-foreground space-y-2 text-sm">
-          <li>Run each guide in a fresh branch or sandbox workspace.</li>
-          <li>Use the linked example package to validate end-to-end.</li>
-          <li>Keep the commands as written to match CI expectations.</li>
-        </ul>
-        <CodeBlock
-          language="bash"
-          filename="guides-quickstart"
-          code={`# list all examples
+			<div className="editorial-panel space-y-4">
+				<div className="flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]">
+					<GitBranch size={16} />
+					Working style
+				</div>
+				<ul className="editorial-list">
+					<li>
+						<span className="editorial-list-marker" />
+						<span>Run each guide in a branch or sandboxed workspace.</span>
+					</li>
+					<li>
+						<span className="editorial-list-marker" />
+						<span>
+							Prefer one bounded surface at a time: one endpoint, one workflow,
+							one integration, one unsafe module.
+						</span>
+					</li>
+					<li>
+						<span className="editorial-list-marker" />
+						<span>
+							Use the example and reference outputs to verify what changed, not
+							just the narrative page.
+						</span>
+					</li>
+				</ul>
+				<CodeBlock
+					language="bash"
+					filename="guides-quickstart"
+					code={`# list example systems
 contractspec examples list
 
-# validate example packages in this repo
+# validate the examples in this workspace
 contractspec examples validate --repo-root .`}
-        />
-      </div>
-    </div>
-  );
+				/>
+			</div>
+		</div>
+	);
 }

package/src/components/docs/guides/guides.docblocks.ts

@@ -2,51 +2,51 @@ import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
 import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
 
 const guideDocBlocks: DocBlock[] = [
-  {
-    id: 'docs.guides.index',
-    title: 'Guides',
-    summary: 'Hands-on guides for adopting ContractSpec in real workflows.',
-    kind: 'goal',
-    visibility: 'public',
-    route: '/docs/guides',
-    tags: ['guides', 'adoption'],
-    body: `# Guides
+	{
+		id: 'docs.guides.index',
+		title: 'Guides',
+		summary: 'Hands-on guides for adopting ContractSpec in real workflows.',
+		kind: 'goal',
+		visibility: 'public',
+		route: '/docs/guides',
+		tags: ['guides', 'adoption'],
+		body: `# Guides
 
 Hands-on, runnable guides that map to real adoption scenarios. Each guide includes commands, expected output, and a CI-verified example package.`,
-  },
-  {
-    id: 'docs.guides.nextjs-one-endpoint',
-    title: 'Next.js one endpoint',
-    summary: 'Add ContractSpec to an existing Next.js app with one endpoint.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/guides/nextjs-one-endpoint',
-    tags: ['guides', 'nextjs', 'operations'],
-    body: `# Add ContractSpec to a Next.js app (one endpoint)
+	},
+	{
+		id: 'docs.guides.nextjs-one-endpoint',
+		title: 'Next.js one endpoint',
+		summary: 'Add ContractSpec to an existing Next.js app with one endpoint.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/nextjs-one-endpoint',
+		tags: ['guides', 'nextjs', 'operations'],
+		body: `# Add ContractSpec to a Next.js app (one endpoint)
 
 Create a single OperationSpec, register it, and expose it through a Next.js App Router handler.`,
-  },
-  {
-    id: 'docs.guides.spec-validation-typing',
-    title: 'Spec validation and typing',
-    summary: 'Define an operation spec with validation and types, no rewrites.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/guides/spec-validation-and-typing',
-    tags: ['guides', 'validation', 'typing'],
-    body: `# Spec-driven validation and typing
+	},
+	{
+		id: 'docs.guides.spec-validation-typing',
+		title: 'Spec validation and typing',
+		summary: 'Define an operation spec with validation and types, no rewrites.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/spec-validation-and-typing',
+		tags: ['guides', 'validation', 'typing'],
+		body: `# Spec-driven validation and typing
 
 Define command/query specs that enforce validation and generate types without rewriting your app.`,
-  },
-  {
-    id: 'docs.guides.docs-clients-schemas',
-    title: 'Generate docs, clients, schemas',
-    summary: 'Generate docs and OpenAPI for client SDKs from specs.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/guides/generate-docs-clients-schemas',
-    tags: ['guides', 'docs', 'openapi'],
-    body: `# Generate docs and client schemas
+	},
+	{
+		id: 'docs.guides.docs-clients-schemas',
+		title: 'Generate docs, clients, schemas',
+		summary: 'Generate docs and OpenAPI for client SDKs from specs.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/generate-docs-clients-schemas',
+		tags: ['guides', 'docs', 'openapi'],
+		body: `# Generate docs and client schemas
 
 Use ContractSpec to generate documentation and OpenAPI exports for client SDKs.
 
@@ -65,16 +65,16 @@ bun docs:generate
 # or versioned output
 bun docs:generate -- --version v1.0.0
 \`\`\``,
-  },
-  {
-    id: 'docs.guides.docs-generation-pipeline',
-    title: 'Docs generation pipeline',
-    summary: 'Wire generated docs into a reference site with chunked indexes.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/guides/docs-generation-pipeline',
-    tags: ['guides', 'docs', 'pipeline'],
-    body: `# Build the docs pipeline
+	},
+	{
+		id: 'docs.guides.docs-generation-pipeline',
+		title: 'Docs generation pipeline',
+		summary: 'Wire generated docs into a reference site with chunked indexes.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/docs-generation-pipeline',
+		tags: ['guides', 'docs', 'pipeline'],
+		body: `# Build the docs pipeline
 
 Use ContractSpec to generate reference markdown, build a chunked index, and wire it into your docs routes.
 
@@ -95,19 +95,19 @@ bun docs:generate -- --version v1.0.0
 ## Reference wiring
 
 Use the generated manifest and chunks under \`docs-index.manifest.json\` and \`docs-index.*.json\` to load the index at runtime.`,
-  },
-  {
-    id: 'docs.guides.ci-contract-diff-gating',
-    title: 'CI gating for contract diffs',
-    summary: 'Gate changes with deterministic diffs and CI checks.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/guides/ci-contract-diff-gating',
-    tags: ['guides', 'ci', 'diff'],
-    body: `# CI gating with deterministic diffs
+	},
+	{
+		id: 'docs.guides.ci-contract-diff-gating',
+		title: 'CI gating for contract diffs',
+		summary: 'Gate changes with deterministic diffs and CI checks.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/ci-contract-diff-gating',
+		tags: ['guides', 'ci', 'diff'],
+		body: `# CI gating with deterministic diffs
 
 Run ContractSpec CI checks to detect drift and breaking changes before merge.`,
-  },
+	},
 ];
 
 registerDocBlocks(guideDocBlocks);

package/src/components/docs/guides/index.ts

@@ -1,10 +1,10 @@
 import './guides.docblocks';
 
-export { GuidesIndexPage } from './GuidesIndexPage';
+export { GuideCIDiffGatingPage } from './GuideCIDiffGatingPage';
 export { GuideContractTypesPage } from './GuideContractTypesPage';
 export { GuideDocsPipelinePage } from './GuideDocsPipelinePage';
-export { GuideNextjsOneEndpointPage } from './GuideNextjsOneEndpointPage';
-export { GuideSpecValidationTypingPage } from './GuideSpecValidationTypingPage';
 export { GuideGenerateDocsClientsSchemasPage } from './GuideGenerateDocsClientsSchemasPage';
-export { GuideCIDiffGatingPage } from './GuideCIDiffGatingPage';
 export { GuideImportExistingCodebasesPage } from './GuideImportExistingCodebasesPage';
+export { GuideNextjsOneEndpointPage } from './GuideNextjsOneEndpointPage';
+export { GuideSpecValidationTypingPage } from './GuideSpecValidationTypingPage';
+export { GuidesIndexPage } from './GuidesIndexPage';

package/src/components/docs/index.ts

@@ -1,58 +1,44 @@
 // Documentation pages organized by domain
 
-// Root docs page
-export { DocsIndexPage } from './DocsIndexPage';
-
-// Getting Started
-export * from './getting-started';
-
-// Specs
-export * from './specs';
-
-// Libraries
-export * from './libraries';
-
-// Architecture
-export * from './architecture';
-
 // Advanced
 export * from './advanced';
-
-// Safety
-export * from './safety';
-
-// Integrations
-export * from './integrations';
-
-// Guides
-export * from './guides';
-
+// Architecture
+export * from './architecture';
+// Comparison
+export * from './comparison';
+// Root docs page
+export { DocsIndexPage } from './DocsIndexPage';
+// Docs manifest
+export * from './docsManifest';
+// Ecosystem
+export * from './ecosystem';
 // Examples
 export * from './examples';
-
-// Reference
-export * from './reference';
-
 // Generated reference artifacts
 export * from './generated';
+// Getting Started
+export * from './getting-started';
 
+// Guides
+export * from './guides';
+// Integrations
+export * from './integrations';
 // Intent Pages
 export * from './intent';
-
-// Ecosystem
-export * from './ecosystem';
-
 // Knowledge
 export * from './knowledge';
-
-// Comparison
-export * from './comparison';
-
-// Ops
-export * from './ops';
-
+// Libraries
+export * from './libraries';
 // Manifesto
 export { ManifestoPage } from './manifesto/ManifestoPage';
+// Ops
+export * from './ops';
+// Reference
+export * from './reference';
+// Safety
+export * from './safety';
+// Specs
+export * from './specs';
 
 // Studio
 export * from './studio';

package/src/components/docs/integrations/IntegrationsCircuitBreakersPage.tsx

@@ -4,25 +4,25 @@
 // };
 
 export function IntegrationsCircuitBreakersPage() {
-  return (
-    <div className="space-y-8">
-      <div className="space-y-4">
-        <h1 className="text-4xl font-bold">Integration Circuit Breakers</h1>
-        <p className="text-muted-foreground text-lg">
-          External APIs are the most common source of instability. Wrap every
-          integration call in a circuit breaker to protect your system.
-        </p>
-      </div>
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">Integration Circuit Breakers</h1>
+				<p className="text-lg text-muted-foreground">
+					External APIs are the most common source of instability. Wrap every
+					integration call in a circuit breaker to protect your system.
+				</p>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Pattern</h2>
-        <p>
-          Create a dedicated circuit breaker instance for each external service.
-          This ensures that a failure in Stripe doesn't trigger the circuit
-          breaker for Twilio.
-        </p>
-        <pre className="bg-muted rounded-lg border p-4 text-sm">
-          {`// integrations/stripe.ts
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Pattern</h2>
+				<p>
+					Create a dedicated circuit breaker instance for each external service.
+					This ensures that a failure in Stripe doesn't trigger the circuit
+					breaker for Twilio.
+				</p>
+				<pre className="rounded-lg border bg-muted p-4 text-sm">
+					{`// integrations/stripe.ts
 import { CircuitBreaker } from '@contractspec/lib.resilience/circuit-breaker';
 
 const stripeBreaker = new CircuitBreaker({
@@ -33,8 +33,8 @@ const stripeBreaker = new CircuitBreaker({
 export async function createCharge(amount: number) {
   return stripeBreaker.execute(() => stripe.charges.create({ amount }));
 }`}
-        </pre>
-      </div>
-    </div>
-  );
+				</pre>
+			</div>
+		</div>
+	);
 }

package/src/components/docs/integrations/IntegrationsElevenLabsPage.tsx

@@ -8,29 +8,29 @@ import { ChevronRight } from 'lucide-react';
 // };
 
 export function IntegrationsElevenLabsPage() {
-  return (
-    <div className="space-y-8">
-      <div className="space-y-4">
-        <h1 className="text-4xl font-bold">ElevenLabs</h1>
-        <p className="text-muted-foreground">
-          ElevenLabs provides state-of-the-art text-to-speech and voice cloning
-          technology. Create natural-sounding voiceovers, audiobooks, and voice
-          assistants.
-        </p>
-      </div>
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">ElevenLabs</h1>
+				<p className="text-muted-foreground">
+					ElevenLabs provides state-of-the-art text-to-speech and voice cloning
+					technology. Create natural-sounding voiceovers, audiobooks, and voice
+					assistants.
+				</p>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Setup</h2>
-        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
-          <pre>{`# .env
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Setup</h2>
+				<div className="overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm">
+					<pre>{`# .env
 ELEVENLABS_API_KEY=...`}</pre>
-        </div>
-      </div>
+				</div>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Text-to-Speech</h2>
-        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
-          <pre>{`capabilityId: elevenlabs-tts
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Text-to-Speech</h2>
+				<div className="overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm">
+					<pre>{`capabilityId: elevenlabs-tts
 provider:
   type: elevenlabs
   operation: textToSpeech
@@ -50,27 +50,27 @@ outputs:
     type: string
   audioData:
     type: buffer`}</pre>
-        </div>
-      </div>
+				</div>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Use cases</h2>
-        <ul className="text-muted-foreground list-inside list-disc space-y-2">
-          <li>Generate voiceovers for videos</li>
-          <li>Create audio versions of articles</li>
-          <li>Build voice assistants</li>
-          <li>Produce audiobooks</li>
-        </ul>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Use cases</h2>
+				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
+					<li>Generate voiceovers for videos</li>
+					<li>Create audio versions of articles</li>
+					<li>Build voice assistants</li>
+					<li>Produce audiobooks</li>
+				</ul>
+			</div>
 
-      <div className="flex items-center gap-4 pt-4">
-        <Link href="/docs/integrations/mistral" className="btn-ghost">
-          Previous: Mistral
-        </Link>
-        <Link href="/docs/integrations/qdrant" className="btn-primary">
-          Next: Qdrant <ChevronRight size={16} />
-        </Link>
-      </div>
-    </div>
-  );
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/integrations/mistral" className="btn-ghost">
+					Previous: Mistral
+				</Link>
+				<Link href="/docs/integrations/qdrant" className="btn-primary">
+					Next: Qdrant <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
 }