@contractspec/bundle.library 1.12.0 → 1.13.0

package/dist/components/docs/guides/index.js

@@ -1,11 +1,2903 @@
-import "./guides.docblocks.js";
-import { GuidesIndexPage } from "./GuidesIndexPage.js";
-import { GuideContractTypesPage } from "./GuideContractTypesPage.js";
-import { GuideDocsPipelinePage } from "./GuideDocsPipelinePage.js";
-import { GuideNextjsOneEndpointPage } from "./GuideNextjsOneEndpointPage.js";
-import { GuideSpecValidationTypingPage } from "./GuideSpecValidationTypingPage.js";
-import { GuideGenerateDocsClientsSchemasPage } from "./GuideGenerateDocsClientsSchemasPage.js";
-import { GuideCIDiffGatingPage } from "./GuideCIDiffGatingPage.js";
-import { GuideImportExistingCodebasesPage } from "./GuideImportExistingCodebasesPage.js";
-
-export { GuideCIDiffGatingPage, GuideContractTypesPage, GuideDocsPipelinePage, GuideGenerateDocsClientsSchemasPage, GuideImportExistingCodebasesPage, GuideNextjsOneEndpointPage, GuideSpecValidationTypingPage, GuidesIndexPage };
+// @bun
+// src/components/docs/shared/StudioPrompt.tsx
+import Link from "@contractspec/lib.ui-link";
+import { jsxDEV } from "react/jsx-dev-runtime";
+function StudioPrompt({
+  title = "Need managed policy gates and approvals?",
+  body = "ContractSpec Studio adds policy gates, remote registry workflows, and audit trails when you are ready to scale adoption.",
+  ctaLabel = "Join Studio waitlist",
+  href = "/contact#waitlist"
+}) {
+  return /* @__PURE__ */ jsxDEV("div", {
+    className: "card-subtle space-y-3 p-6",
+    children: [
+      /* @__PURE__ */ jsxDEV("h3", {
+        className: "text-lg font-semibold",
+        children: title
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("p", {
+        className: "text-muted-foreground text-sm",
+        children: body
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV(Link, {
+        href,
+        className: "btn-primary",
+        children: ctaLabel
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideCIDiffGatingPage.tsx
+import { CodeBlock } from "@contractspec/lib.design-system";
+import Link2 from "@contractspec/lib.ui-link";
+import { ChevronRight } from "lucide-react";
+import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+function GuideCIDiffGatingPage() {
+  return /* @__PURE__ */ jsxDEV2("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV2("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV2("h1", {
+            className: "text-4xl font-bold",
+            children: "CI gating with deterministic diffs"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV2("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Add ContractSpec CI checks that validate specs, detect drift, and gate breaking changes before merge."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV2("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV2("h2", {
+            className: "text-2xl font-bold",
+            children: "What you'll build"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV2("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV2("li", {
+                children: "CI workflow running ContractSpec validation and drift checks."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("li", {
+                children: "Machine-readable output for PR annotations."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("li", {
+                children: "Deterministic contract diffs in review."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV2("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV2("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV2("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Add the CI workflow"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Copy the template from the CLI package."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2(CodeBlock, {
+                language: "bash",
+                filename: "ci-copy",
+                code: `cp node_modules/@contractspec/app.cli-contractspec/templates/github-action.yml .github/workflows/contractspec.yml`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: new workflow file in ",
+                  /* @__PURE__ */ jsxDEV2("code", {
+                    children: ".github/workflows"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV2("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV2("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Run CI locally"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2(CodeBlock, {
+                language: "bash",
+                filename: "ci-local",
+                code: `contractspec ci --format json --check-drift`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Expected output: JSON summary including pass/fail counts and drift status (if configured)."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV2("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV2("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Add a diff check"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Use the diff command to inspect breaking changes in PRs."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2(CodeBlock, {
+                language: "bash",
+                filename: "ci-diff",
+                code: `contractspec diff src/contracts/spec-v1.ts src/contracts/spec-v2.ts --breaking`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Expected output: deterministic diff with breaking change hints."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV2("div", {
+            className: "card-subtle space-y-3 p-6",
+            children: [
+              /* @__PURE__ */ jsxDEV2("h3", {
+                className: "text-lg font-semibold",
+                children: "Example package"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2("p", {
+                className: "text-muted-foreground text-sm",
+                children: "The CRM pipeline example is already wired in the quickstart smoke test. Use it as a CI-ready template."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV2(CodeBlock, {
+                language: "bash",
+                filename: "crm-ci",
+                code: `cd packages/examples/crm-pipeline
+bun run build
+bun run validate`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV2(StudioPrompt, {
+            title: "Need managed CI policy gates?",
+            body: "Studio adds policy approvals, drift dashboards, and audit trails after CI checks pass."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV2("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV2(Link2, {
+            href: "/docs/guides",
+            className: "btn-primary",
+            children: [
+              "Back to guides ",
+              /* @__PURE__ */ jsxDEV2(ChevronRight, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV2(Link2, {
+            href: "/docs",
+            className: "btn-ghost",
+            children: "Docs home"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideContractTypesPage.tsx
+import { CodeBlock as CodeBlock2 } from "@contractspec/lib.design-system";
+import Link3 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight2, Layers, Zap, Shield, Globe } from "lucide-react";
+import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
+var contractTypes = [
+  {
+    name: "Operations",
+    factory: "defineCommand / defineQuery",
+    description: "API endpoints with input/output schemas, validation, and policy.",
+    icon: Zap,
+    color: "text-blue-400"
+  },
+  {
+    name: "Events",
+    factory: "defineEvent",
+    description: "Domain events with typed payloads and PII handling.",
+    icon: Layers,
+    color: "text-green-400"
+  },
+  {
+    name: "Capabilities",
+    factory: "defineCapability",
+    description: "Feature groupings that link operations, events, and UIs.",
+    icon: Shield,
+    color: "text-purple-400"
+  },
+  {
+    name: "Presentations",
+    factory: "definePresentation",
+    description: "UI specifications for rendering data and handling interactions.",
+    icon: Globe,
+    color: "text-orange-400"
+  }
+];
+function GuideContractTypesPage() {
+  return /* @__PURE__ */ jsxDEV3("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV3("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV3("h1", {
+            className: "text-4xl font-bold",
+            children: "Contract Types Overview"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV3("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Learn about the different contract types in ContractSpec and when to use each one for spec-first development."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV3("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV3("h2", {
+            className: "text-2xl font-bold",
+            children: "Core Contract Types"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "grid gap-3 md:grid-cols-2",
+            children: contractTypes.map((type) => /* @__PURE__ */ jsxDEV3("div", {
+              className: "flex items-start gap-3 rounded-lg border border-white/10 p-4",
+              children: [
+                /* @__PURE__ */ jsxDEV3(type.icon, {
+                  className: type.color,
+                  size: 20
+                }, undefined, false, undefined, this),
+                /* @__PURE__ */ jsxDEV3("div", {
+                  className: "space-y-1",
+                  children: [
+                    /* @__PURE__ */ jsxDEV3("h3", {
+                      className: "font-semibold",
+                      children: type.name
+                    }, undefined, false, undefined, this),
+                    /* @__PURE__ */ jsxDEV3("p", {
+                      className: "text-muted-foreground text-xs",
+                      children: type.description
+                    }, undefined, false, undefined, this),
+                    /* @__PURE__ */ jsxDEV3("code", {
+                      className: "text-xs text-violet-400",
+                      children: type.factory
+                    }, undefined, false, undefined, this)
+                  ]
+                }, undefined, true, undefined, this)
+              ]
+            }, type.name, true, undefined, this))
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV3("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Operations (Commands & Queries)"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Operations are the backbone of your API. Commands mutate state, queries read state. Both have typed input/output schemas."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3(CodeBlock2, {
+                language: "typescript",
+                filename: "src/contracts/user.operation.ts",
+                code: `import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+// Command: Mutates state (creates a user)
+export const CreateUserCommand = defineCommand({
+  meta: {
+    key: "user.create",
+    version: "1.0.0",
+    description: "Create a new user account",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users", "auth"],
+  },
+  io: {
+    input: new SchemaModel({
+      name: "CreateUserInput",
+      fields: {
+        email: { type: ScalarTypeEnum.Email(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+      },
+    }),
+    output: new SchemaModel({
+      name: "CreateUserOutput",
+      fields: {
+        id: { type: ScalarTypeEnum.UUID(), isOptional: false },
+        email: { type: ScalarTypeEnum.Email(), isOptional: false },
+      },
+    }),
+    errors: {
+      EMAIL_EXISTS: {
+        description: "Email already registered",
+        http: 409,
+        when: "User with this email already exists",
+      },
+    },
+  },
+  policy: { auth: "admin" },
+});
+
+// Query: Reads state (gets user by ID)
+export const GetUserQuery = defineQuery({
+  meta: {
+    key: "user.get",
+    version: "1.0.0",
+    description: "Get user by ID",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users"],
+  },
+  io: {
+    input: new SchemaModel({
+      name: "GetUserInput",
+      fields: {
+        id: { type: ScalarTypeEnum.UUID(), isOptional: false },
+      },
+    }),
+    output: new SchemaModel({
+      name: "GetUserOutput",
+      fields: {
+        id: { type: ScalarTypeEnum.UUID(), isOptional: false },
+        email: { type: ScalarTypeEnum.Email(), isOptional: false },
+        name: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: "user" },
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Events"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Events represent domain occurrences. They have typed payloads with PII field marking for compliance."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3(CodeBlock2, {
+                language: "typescript",
+                filename: "src/contracts/user.event.ts",
+                code: `import { defineEvent } from "@contractspec/lib.contracts";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+export const UserCreatedEvent = defineEvent({
+  meta: {
+    key: "user.created",
+    version: "1.0.0",
+    description: "Emitted when a new user is created",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users", "auth"],
+  },
+  // Mark PII fields for redaction in logs/exports
+  pii: ["email"],
+  payload: new SchemaModel({
+    name: "UserCreatedPayload",
+    fields: {
+      userId: { type: ScalarTypeEnum.UUID(), isOptional: false },
+      email: { type: ScalarTypeEnum.Email(), isOptional: false },
+      createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    },
+  }),
+});
+
+export const UserDeletedEvent = defineEvent({
+  meta: {
+    key: "user.deleted",
+    version: "1.0.0",
+    description: "Emitted when a user is deleted",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users"],
+  },
+  payload: new SchemaModel({
+    name: "UserDeletedPayload",
+    fields: {
+      userId: { type: ScalarTypeEnum.UUID(), isOptional: false },
+      deletedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+      reason: { type: ScalarTypeEnum.String(), isOptional: true },
+    },
+  }),
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Capabilities"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Capabilities group related operations, events, and presentations. They define feature boundaries and dependencies."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3(CodeBlock2, {
+                language: "typescript",
+                filename: "src/contracts/user-management.capability.ts",
+                code: `import { defineCapability } from "@contractspec/lib.contracts";
+
+export const UserManagementCapability = defineCapability({
+  meta: {
+    key: "user.management",
+    version: "1.0.0",
+    description: "User account management features",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users", "core"],
+    kind: "api",
+  },
+  // Operations/events this capability provides
+  provides: [
+    { surface: "operation", key: "user.create", version: "1.0.0" },
+    { surface: "operation", key: "user.get", version: "1.0.0" },
+    { surface: "operation", key: "user.delete", version: "1.0.0" },
+    { surface: "event", key: "user.created", version: "1.0.0" },
+    { surface: "event", key: "user.deleted", version: "1.0.0" },
+  ],
+  // Dependencies on other capabilities
+  requires: [
+    { key: "auth.core", reason: "Needs authentication for user operations" },
+  ],
+});
+
+// Capabilities can extend other capabilities
+export const AdminUserCapability = defineCapability({
+  meta: {
+    key: "user.admin",
+    version: "1.0.0",
+    description: "Admin-only user management features",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users", "admin"],
+    kind: "api",
+  },
+  // Inherit from base capability
+  extends: { key: "user.management", version: "1.0.0" },
+  provides: [
+    { surface: "operation", key: "user.ban", version: "1.0.0" },
+    { surface: "operation", key: "user.impersonate", version: "1.0.0" },
+  ],
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h2", {
+                className: "text-2xl font-bold",
+                children: "4) Presentations"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Presentations define UI specifications. They link to capabilities and specify how data should be displayed."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3(CodeBlock2, {
+                language: "typescript",
+                filename: "src/contracts/user-list.presentation.ts",
+                code: `import { definePresentation } from "@contractspec/lib.contracts";
+
+export const UserListPresentation = definePresentation({
+  meta: {
+    key: "users.list",
+    version: "1.0.0",
+    description: "Display a list of users with search and pagination",
+    stability: "stable",
+    owners: ["platform.core"],
+    tags: ["users", "ui"],
+  },
+  // Link to capability that provides data
+  capability: { key: "user.management", version: "1.0.0" },
+  // UI specifications
+  config: {
+    title: "Users",
+    layout: "table",
+    columns: ["name", "email", "createdAt", "status"],
+    actions: ["view", "edit", "delete"],
+    pagination: { defaultPageSize: 25 },
+    search: { fields: ["name", "email"] },
+  },
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h2", {
+                className: "text-2xl font-bold",
+                children: "5) Additional Contract Types"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("p", {
+                className: "text-muted-foreground text-sm",
+                children: "ContractSpec provides specialized contracts for different concerns:"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("div", {
+                className: "grid gap-4 md:grid-cols-2",
+                children: [
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Policy"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "definePolicy"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "RBAC/ABAC rules, rate limits, and access control."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Workflow"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineWorkflow"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "Multi-step processes with states, transitions, and SLAs."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Translation"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineTranslation"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "i18n messages with ICU format and locale fallbacks."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Integration"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineIntegration"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "External service connections and API adapters."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Form"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineFormSpec"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "Form definitions with fields, validation, and layouts."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Data View"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineDataView"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "Read-only data projections and aggregations."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Feature"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineFeature"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "Feature flags and progressive rollout configurations."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("h3", {
+                        className: "font-semibold",
+                        children: "Test"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("code", {
+                        className: "text-xs text-violet-400",
+                        children: "defineTestSpec"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("p", {
+                        className: "text-muted-foreground text-xs",
+                        children: "Contract-driven test scenarios and fixtures."
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h2", {
+                className: "text-2xl font-bold",
+                children: "6) Registering Contracts"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Each contract type has a registry for lookup and validation."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3(CodeBlock2, {
+                language: "typescript",
+                filename: "src/contracts/registry.ts",
+                code: `import {
+  OperationSpecRegistry,
+  installOp,
+} from "@contractspec/lib.contracts/operations";
+import { EventRegistry } from "@contractspec/lib.contracts";
+import { CapabilityRegistry } from "@contractspec/lib.contracts/capabilities";
+
+// Import your contracts
+import { CreateUserCommand, GetUserQuery } from "./user.operation";
+import { UserCreatedEvent } from "./user.event";
+import { UserManagementCapability } from "./user-management.capability";
+
+// Create registries
+export const operationRegistry = new OperationSpecRegistry();
+export const eventRegistry = new EventRegistry();
+export const capabilityRegistry = new CapabilityRegistry();
+
+// Register operations with handlers
+installOp(operationRegistry, CreateUserCommand, async (input) => {
+  // Your implementation here
+  return { id: "uuid", email: input.email };
+});
+
+installOp(operationRegistry, GetUserQuery, async (input) => {
+  // Your implementation here
+  return { id: input.id, email: "user@example.com", name: "User" };
+});
+
+// Register events and capabilities
+eventRegistry.register(UserCreatedEvent);
+capabilityRegistry.register(UserManagementCapability);`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3("div", {
+            className: "card-subtle space-y-3 p-6",
+            children: [
+              /* @__PURE__ */ jsxDEV3("h3", {
+                className: "text-lg font-semibold",
+                children: "Contract Type Decision Guide"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV3("table", {
+                className: "w-full text-sm",
+                children: [
+                  /* @__PURE__ */ jsxDEV3("thead", {
+                    children: /* @__PURE__ */ jsxDEV3("tr", {
+                      className: "border-b border-white/10",
+                      children: [
+                        /* @__PURE__ */ jsxDEV3("th", {
+                          className: "py-2 text-left",
+                          children: "When you need..."
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV3("th", {
+                          className: "py-2 text-left",
+                          children: "Use this contract"
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV3("tbody", {
+                    className: "text-muted-foreground",
+                    children: [
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        className: "border-b border-white/5",
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "An API endpoint that changes data"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "defineCommand"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        className: "border-b border-white/5",
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "An API endpoint that reads data"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "defineQuery"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        className: "border-b border-white/5",
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "Async notification of something that happened"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "defineEvent"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        className: "border-b border-white/5",
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "Group related specs under a feature"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "defineCapability"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        className: "border-b border-white/5",
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "Define UI rendering specifications"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "definePresentation"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        className: "border-b border-white/5",
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "Access control and rate limiting"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "definePolicy"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this),
+                      /* @__PURE__ */ jsxDEV3("tr", {
+                        children: [
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: "Multi-step business processes"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV3("td", {
+                            className: "py-2",
+                            children: /* @__PURE__ */ jsxDEV3("code", {
+                              children: "defineWorkflow"
+                            }, undefined, false, undefined, this)
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3(StudioPrompt, {
+            title: "Want visual contract design?",
+            body: "Studio provides a visual editor for creating and managing contracts with team collaboration and version control."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV3("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV3(Link3, {
+            href: "/docs/guides/nextjs-one-endpoint",
+            className: "btn-primary",
+            children: [
+              "Next: Add your first endpoint ",
+              /* @__PURE__ */ jsxDEV3(ChevronRight2, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV3(Link3, {
+            href: "/docs/guides",
+            className: "btn-ghost",
+            children: "Back to guides"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideDocsPipelinePage.tsx
+import { CodeBlock as CodeBlock3 } from "@contractspec/lib.design-system";
+import Link4 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight3 } from "lucide-react";
+import { jsxDEV as jsxDEV4 } from "react/jsx-dev-runtime";
+function GuideDocsPipelinePage() {
+  return /* @__PURE__ */ jsxDEV4("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV4("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV4("h1", {
+            className: "text-4xl font-bold",
+            children: "Build the docs pipeline"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV4("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Generate reference docs, chunk the index, and wire the docs pages the same way this repo does."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV4("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV4("h2", {
+            className: "text-2xl font-bold",
+            children: "What you'll build"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV4("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV4("li", {
+                children: "Generated Markdown and a chunked index manifest."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4("li", {
+                children: "Reference routes powered by the docs loader."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4("li", {
+                children: "Versioned outputs you can publish per release."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV4("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV4("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV4("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Generate contract docs"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4(CodeBlock3, {
+                language: "bash",
+                filename: "generate-contract-docs",
+                code: `contractspec generate`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: Markdown in ",
+                  /* @__PURE__ */ jsxDEV4("code", {
+                    children: "generated/docs"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV4("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV4("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Build the docs index"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4(CodeBlock3, {
+                language: "bash",
+                filename: "docs-generate",
+                code: `bun docs:generate
+# versioned output
+bun docs:generate -- --version v1.0.0`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "This writes ",
+                  /* @__PURE__ */ jsxDEV4("code", {
+                    children: "docs-index.manifest.json"
+                  }, undefined, false, undefined, this),
+                  " and chunked",
+                  /* @__PURE__ */ jsxDEV4("code", {
+                    children: "docs-index.*.json"
+                  }, undefined, false, undefined, this),
+                  " files in the generated docs bundle."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV4("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV4("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Wire reference routes"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4(CodeBlock3, {
+                language: "tsx",
+                filename: "docs-reference-route",
+                code: `import { notFound } from "next/navigation";
+import {
+  DocsReferenceIndexPage,
+  DocsReferencePage,
+  getGeneratedDocById,
+  listGeneratedDocs,
+} from "@contractspec/bundle.library";
+
+export async function generateStaticParams() {
+  const docs = await listGeneratedDocs();
+  return docs.map((doc) => ({ slug: doc.id.split("/") }));
+}
+
+export default async function Page({ params }: { params: { slug?: string[] } }) {
+  const slug = params.slug?.join("/") ?? "";
+  const doc = await getGeneratedDocById(slug);
+  if (!doc) notFound();
+  return <DocsReferencePage entry={doc.entry} content={doc.content} />;
+}`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Use the index page on ",
+                  /* @__PURE__ */ jsxDEV4("code", {
+                    children: "/docs/reference"
+                  }, undefined, false, undefined, this),
+                  " to render the searchable list."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV4("div", {
+            className: "card-subtle space-y-3 p-6",
+            children: [
+              /* @__PURE__ */ jsxDEV4("h3", {
+                className: "text-lg font-semibold",
+                children: "Repo reference"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV4("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "This repo wires docs under",
+                  " ",
+                  /* @__PURE__ */ jsxDEV4("code", {
+                    children: "packages/apps/web-landing/src/app/docs/reference"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV4(StudioPrompt, {
+            title: "Need hosted docs releases?",
+            body: "Studio can publish versioned docs bundles with approvals and audit trails."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV4("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV4(Link4, {
+            href: "/docs/guides/ci-contract-diff-gating",
+            className: "btn-primary",
+            children: [
+              "Next: CI gating ",
+              /* @__PURE__ */ jsxDEV4(ChevronRight3, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV4(Link4, {
+            href: "/docs/guides",
+            className: "btn-ghost",
+            children: "Back to guides"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideGenerateDocsClientsSchemasPage.tsx
+import { CodeBlock as CodeBlock4 } from "@contractspec/lib.design-system";
+import Link5 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight4 } from "lucide-react";
+import { jsxDEV as jsxDEV5 } from "react/jsx-dev-runtime";
+function GuideGenerateDocsClientsSchemasPage() {
+  return /* @__PURE__ */ jsxDEV5("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV5("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV5("h1", {
+            className: "text-4xl font-bold",
+            children: "Generate docs + client schemas"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV5("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Generate docs and OpenAPI output from ContractSpec operations to power SDKs, docs sites, and tooling."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV5("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV5("h2", {
+            className: "text-2xl font-bold",
+            children: "What you'll build"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV5("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV5("li", {
+                children: "Export docs from your specs."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("li", {
+                children: "Emit OpenAPI 3.1 for client SDK generation."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("li", {
+                children: "Keep outputs deterministic with CI validation."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV5("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV5("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV5("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Generate docs"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Use the generator to emit docs from your contracts."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5(CodeBlock4, {
+                language: "bash",
+                filename: "generate-docs",
+                code: `contractspec generate`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: ",
+                  /* @__PURE__ */ jsxDEV5("code", {
+                    children: "Generate X doc files in generated/docs"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV5("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV5("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Export OpenAPI"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Export an OpenAPI document from your registry module."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5(CodeBlock4, {
+                language: "bash",
+                filename: "openapi-export",
+                code: `contractspec openapi export --registry ./src/contracts/registry.ts --out ./generated/openapi.json`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output:",
+                  " ",
+                  /* @__PURE__ */ jsxDEV5("code", {
+                    children: "OpenAPI written to .../generated/openapi.json"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV5("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV5("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Validate specs"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5(CodeBlock4, {
+                language: "bash",
+                filename: "validate-specs",
+                code: `contractspec validate`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: ",
+                  /* @__PURE__ */ jsxDEV5("code", {
+                    children: "Validation passed"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV5("div", {
+            className: "card-subtle space-y-3 p-6",
+            children: [
+              /* @__PURE__ */ jsxDEV5("h3", {
+                className: "text-lg font-semibold",
+                children: "Example package"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5("p", {
+                className: "text-muted-foreground text-sm",
+                children: "The Integration Hub example provides a full registry of operations and is a good source for OpenAPI exports."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV5(CodeBlock4, {
+                language: "bash",
+                filename: "integration-hub-example",
+                code: `contractspec examples show integration-hub
+
+# openapi export against your registry module
+contractspec openapi export --registry ./src/contracts/registry.ts --out ./generated/openapi.json`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV5(StudioPrompt, {
+            title: "Want managed schema releases?",
+            body: "Studio can publish OpenAPI, SDKs, and release notes automatically with approvals."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV5("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV5(Link5, {
+            href: "/docs/guides/docs-generation-pipeline",
+            className: "btn-primary",
+            children: [
+              "Next: Docs pipeline ",
+              /* @__PURE__ */ jsxDEV5(ChevronRight4, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV5(Link5, {
+            href: "/docs/guides",
+            className: "btn-ghost",
+            children: "Back to guides"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideImportExistingCodebasesPage.tsx
+import { CodeBlock as CodeBlock5 } from "@contractspec/lib.design-system";
+import Link6 from "@contractspec/lib.ui-link";
+import {
+  ChevronRight as ChevronRight5,
+  FileCode,
+  Scan,
+  Settings,
+  AlertCircle
+} from "lucide-react";
+import { jsxDEV as jsxDEV6 } from "react/jsx-dev-runtime";
+var supportedFrameworks = [
+  {
+    name: "NestJS",
+    flag: "nestjs",
+    description: "Controllers, decorators, DTOs"
+  },
+  {
+    name: "Express",
+    flag: "express",
+    description: "Router methods, middleware"
+  },
+  {
+    name: "Fastify",
+    flag: "fastify",
+    description: "Route definitions, schemas"
+  },
+  {
+    name: "Hono",
+    flag: "hono",
+    description: "Route handlers, validators"
+  },
+  {
+    name: "Elysia",
+    flag: "elysia",
+    description: "Type-safe routes, schemas"
+  },
+  {
+    name: "tRPC",
+    flag: "trpc",
+    description: "Procedure definitions"
+  },
+  {
+    name: "Next.js",
+    flag: "next-api",
+    description: "API routes (app/api, pages/api)"
+  }
+];
+function GuideImportExistingCodebasesPage() {
+  return /* @__PURE__ */ jsxDEV6("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV6("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV6("h1", {
+            className: "text-4xl font-bold",
+            children: "Import Existing Codebases"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV6("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Convert your existing API endpoints into ContractSpec contracts. Auto-detect frameworks, extract schemas, and generate spec-first definitions from your code."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV6("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV6("h2", {
+            className: "text-2xl font-bold",
+            children: "What you'll learn"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV6("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV6("li", {
+                children: "How to import existing API endpoints as ContractSpec contracts."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("li", {
+                children: "Framework-specific patterns and auto-detection."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("li", {
+                children: "Customizing imports with scopes, dry-run, and output options."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("li", {
+                children: "Registering imported contracts and adding handlers."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV6("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "Why import existing code?"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Instead of writing contracts from scratch, the import command extracts endpoint patterns from your existing codebase. This gives you:"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("ul", {
+                className: "text-muted-foreground list-disc space-y-1 pl-5 text-sm",
+                children: [
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: "Instant spec coverage for existing APIs"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: "Type-safe schemas derived from your existing types"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: "A foundation to iterate and refine contracts"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: "Gradual adoption without rewriting code"
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "Supported frameworks"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("div", {
+                className: "grid gap-3 md:grid-cols-2 lg:grid-cols-3",
+                children: supportedFrameworks.map((fw) => /* @__PURE__ */ jsxDEV6("div", {
+                  className: "flex items-start gap-3 rounded-lg border border-white/10 p-4",
+                  children: [
+                    /* @__PURE__ */ jsxDEV6(FileCode, {
+                      className: "text-violet-400",
+                      size: 18
+                    }, undefined, false, undefined, this),
+                    /* @__PURE__ */ jsxDEV6("div", {
+                      className: "space-y-1",
+                      children: [
+                        /* @__PURE__ */ jsxDEV6("h3", {
+                          className: "font-semibold",
+                          children: fw.name
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("p", {
+                          className: "text-muted-foreground text-xs",
+                          children: fw.description
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("code", {
+                          className: "text-xs text-violet-400",
+                          children: [
+                            "--framework ",
+                            fw.flag
+                          ]
+                        }, undefined, true, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  ]
+                }, fw.flag, true, undefined, this))
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Quick start"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Run the import command to auto-detect your framework and extract endpoints:"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "bash",
+                filename: "import-quickstart",
+                code: `# Auto-detect framework and import all endpoints
+contractspec import ./src
+
+# Preview what would be imported (dry-run)
+contractspec import ./src --dry-run
+
+# Force a specific framework
+contractspec import ./src --framework nestjs`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Expected output: A summary of endpoints found, schemas extracted, and files generated."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Framework-specific patterns"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: "The import command recognizes these patterns in each framework:"
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h3", {
+                className: "flex items-center gap-2 text-xl font-semibold",
+                children: [
+                  /* @__PURE__ */ jsxDEV6(Scan, {
+                    size: 18,
+                    className: "text-blue-400"
+                  }, undefined, false, undefined, this),
+                  "NestJS"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "typescript",
+                filename: "src/users/users.controller.ts (before)",
+                code: `@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async getUser(@Param('id') id: string): Promise<UserDto> {
+    return this.usersService.findOne(id);
+  }
+
+  @Post()
+  @UseGuards(AuthGuard)
+  async createUser(@Body() dto: CreateUserDto): Promise<UserDto> {
+    return this.usersService.create(dto);
+  }
+}`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Detected: ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "@Controller"
+                  }, undefined, false, undefined, this),
+                  ", ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "@Get"
+                  }, undefined, false, undefined, this),
+                  ",",
+                  " ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "@Post"
+                  }, undefined, false, undefined, this),
+                  ", ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "@Body"
+                  }, undefined, false, undefined, this),
+                  ", ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "@Param"
+                  }, undefined, false, undefined, this),
+                  ",",
+                  " ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "@UseGuards"
+                  }, undefined, false, undefined, this),
+                  " decorators."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h3", {
+                className: "flex items-center gap-2 text-xl font-semibold",
+                children: [
+                  /* @__PURE__ */ jsxDEV6(Scan, {
+                    size: 18,
+                    className: "text-green-400"
+                  }, undefined, false, undefined, this),
+                  "Express"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "typescript",
+                filename: "src/routes/users.ts (before)",
+                code: `const router = express.Router();
+
+router.get('/users/:id', async (req, res) => {
+  const user = await getUserById(req.params.id);
+  res.json(user);
+});
+
+router.post('/users', validateBody(CreateUserSchema), async (req, res) => {
+  const user = await createUser(req.body);
+  res.status(201).json(user);
+});`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Detected: ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "router.get"
+                  }, undefined, false, undefined, this),
+                  ", ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "router.post"
+                  }, undefined, false, undefined, this),
+                  ", validation middleware, Zod schemas."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h3", {
+                className: "flex items-center gap-2 text-xl font-semibold",
+                children: [
+                  /* @__PURE__ */ jsxDEV6(Scan, {
+                    size: 18,
+                    className: "text-purple-400"
+                  }, undefined, false, undefined, this),
+                  "Next.js API Routes"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "typescript",
+                filename: "app/api/users/[id]/route.ts (before)",
+                code: `export async function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  const user = await getUserById(params.id);
+  return Response.json(user);
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const user = await createUser(body);
+  return Response.json(user, { status: 201 });
+}`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Detected: ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "GET"
+                  }, undefined, false, undefined, this),
+                  ", ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "POST"
+                  }, undefined, false, undefined, this),
+                  " exports in",
+                  " ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "app/api/**/route.ts"
+                  }, undefined, false, undefined, this),
+                  " and ",
+                  /* @__PURE__ */ jsxDEV6("code", {
+                    children: "pages/api/**/*.ts"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Understanding generated contracts"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: "The import command generates ContractSpec operations with TODO placeholders for fields it cannot infer:"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "typescript",
+                filename: ".contractspec/generated/users.operation.ts",
+                code: `import { defineQuery, defineCommand } from "@contractspec/lib.contracts";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+export const GetUserQuery = defineQuery({
+  meta: {
+    key: "users.get",
+    version: "1.0.0",
+    description: "TODO: Add description",
+    stability: "draft",
+    owners: ["TODO"],
+    tags: ["users"],
+  },
+  io: {
+    input: new SchemaModel({
+      name: "GetUserInput",
+      fields: {
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+    output: new SchemaModel({
+      name: "GetUserOutput",
+      fields: {
+        // TODO: Add output fields based on your UserDto
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: "user" }, // Inferred from @UseGuards
+  transport: {
+    rest: { method: "GET", path: "/users/:id" },
+  },
+});
+
+export const CreateUserCommand = defineCommand({
+  meta: {
+    key: "users.create",
+    version: "1.0.0",
+    description: "TODO: Add description",
+    stability: "draft",
+    owners: ["TODO"],
+    tags: ["users"],
+  },
+  io: {
+    input: new SchemaModel({
+      name: "CreateUserInput",
+      fields: {
+        // TODO: Add fields from CreateUserDto
+      },
+    }),
+    output: new SchemaModel({
+      name: "CreateUserOutput",
+      fields: {
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: "admin" },
+  transport: {
+    rest: { method: "POST", path: "/users" },
+  },
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "4) Customizing imports"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("div", {
+                className: "flex items-center gap-2",
+                children: [
+                  /* @__PURE__ */ jsxDEV6(Settings, {
+                    size: 18,
+                    className: "text-violet-400"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("h3", {
+                    className: "text-lg font-semibold",
+                    children: "Available options"
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV6("div", {
+                className: "overflow-x-auto",
+                children: /* @__PURE__ */ jsxDEV6("table", {
+                  className: "w-full text-sm",
+                  children: [
+                    /* @__PURE__ */ jsxDEV6("thead", {
+                      children: /* @__PURE__ */ jsxDEV6("tr", {
+                        className: "border-b border-white/10",
+                        children: [
+                          /* @__PURE__ */ jsxDEV6("th", {
+                            className: "py-2 pr-4 text-left",
+                            children: "Option"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV6("th", {
+                            className: "py-2 pr-4 text-left",
+                            children: "Description"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV6("th", {
+                            className: "py-2 text-left",
+                            children: "Example"
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this)
+                    }, undefined, false, undefined, this),
+                    /* @__PURE__ */ jsxDEV6("tbody", {
+                      className: "text-muted-foreground",
+                      children: [
+                        /* @__PURE__ */ jsxDEV6("tr", {
+                          className: "border-b border-white/5",
+                          children: [
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--scope"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: "Limit to specific directories"
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--scope src/users src/auth"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, undefined, true, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("tr", {
+                          className: "border-b border-white/5",
+                          children: [
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--framework"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: "Force a specific framework"
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--framework express"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, undefined, true, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("tr", {
+                          className: "border-b border-white/5",
+                          children: [
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--output"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: "Output directory"
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--output ./contracts"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, undefined, true, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("tr", {
+                          className: "border-b border-white/5",
+                          children: [
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--dry-run"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: "Preview without writing files"
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--dry-run"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, undefined, true, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("tr", {
+                          className: "border-b border-white/5",
+                          children: [
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--analyze"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: "Analysis only, no code generation"
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--analyze"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, undefined, true, undefined, this),
+                        /* @__PURE__ */ jsxDEV6("tr", {
+                          children: [
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--json"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2 pr-4",
+                              children: "Output as JSON for scripting"
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV6("td", {
+                              className: "py-2",
+                              children: /* @__PURE__ */ jsxDEV6("code", {
+                                children: "--json"
+                              }, undefined, false, undefined, this)
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, undefined, true, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  ]
+                }, undefined, true, undefined, this)
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "bash",
+                filename: "import-options",
+                code: `# Import only specific modules
+contractspec import ./src --scope src/users src/orders
+
+# Preview with analysis
+contractspec import ./src --dry-run --analyze
+
+# Output to custom directory
+contractspec import ./src --output ./src/contracts/generated
+
+# Get JSON for CI/scripting
+contractspec import ./src --json > import-result.json`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "5) Registering imported contracts"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("p", {
+                className: "text-muted-foreground text-sm",
+                children: "After import, register contracts and add handlers:"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6(CodeBlock5, {
+                language: "typescript",
+                filename: "src/contracts/registry.ts",
+                code: `import {
+  OperationSpecRegistry,
+  installOp,
+} from "@contractspec/lib.contracts/operations";
+import {
+  GetUserQuery,
+  CreateUserCommand,
+} from "./.contractspec/generated/users.operation";
+
+export const registry = new OperationSpecRegistry();
+
+// Add handlers to imported operations
+installOp(registry, GetUserQuery, async (input) => {
+  const user = await db.user.findUnique({ where: { id: input.id } });
+  return user;
+});
+
+installOp(registry, CreateUserCommand, async (input) => {
+  const user = await db.user.create({ data: input });
+  return { id: user.id };
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "text-2xl font-bold",
+                children: "6) After importing"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV6("ol", {
+                className: "text-muted-foreground list-decimal space-y-2 pl-5 text-sm",
+                children: [
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("strong", {
+                        children: "Review generated contracts"
+                      }, undefined, false, undefined, this),
+                      " \u2014 Check the TODO placeholders and fill in descriptions, owners, and tags."
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("strong", {
+                        children: "Refine schemas"
+                      }, undefined, false, undefined, this),
+                      " \u2014 Add proper types, validation rules, and error definitions."
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("strong", {
+                        children: "Run validation"
+                      }, undefined, false, undefined, this),
+                      " \u2014",
+                      " ",
+                      /* @__PURE__ */ jsxDEV6("code", {
+                        children: "contractspec validate"
+                      }, undefined, false, undefined, this),
+                      " to ensure contracts are valid."
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("strong", {
+                        children: "Register and wire handlers"
+                      }, undefined, false, undefined, this),
+                      " \u2014 Connect contracts to your existing business logic."
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("li", {
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("strong", {
+                        children: "Iterate"
+                      }, undefined, false, undefined, this),
+                      " \u2014 The imported contracts are a starting point. Refine them as your spec matures."
+                    ]
+                  }, undefined, true, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV6("h2", {
+                className: "flex items-center gap-2 text-2xl font-bold",
+                children: [
+                  /* @__PURE__ */ jsxDEV6(AlertCircle, {
+                    size: 20,
+                    className: "text-yellow-400"
+                  }, undefined, false, undefined, this),
+                  "Troubleshooting"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV6("div", {
+                className: "space-y-4",
+                children: [
+                  /* @__PURE__ */ jsxDEV6("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("h3", {
+                        className: "font-semibold",
+                        children: "Framework not detected"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV6("p", {
+                        className: "text-muted-foreground text-sm",
+                        children: [
+                          "Use ",
+                          /* @__PURE__ */ jsxDEV6("code", {
+                            children: "--framework <name>"
+                          }, undefined, false, undefined, this),
+                          " to force a specific framework. Check that your entry files follow standard patterns."
+                        ]
+                      }, undefined, true, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("h3", {
+                        className: "font-semibold",
+                        children: "Missing schemas"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV6("p", {
+                        className: "text-muted-foreground text-sm",
+                        children: [
+                          "Schema inference works best with explicit types. If using",
+                          " ",
+                          /* @__PURE__ */ jsxDEV6("code", {
+                            children: "any"
+                          }, undefined, false, undefined, this),
+                          " or dynamic types, you'll see TODO placeholders. Fill them in manually."
+                        ]
+                      }, undefined, true, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV6("div", {
+                    className: "card-subtle space-y-2 p-4",
+                    children: [
+                      /* @__PURE__ */ jsxDEV6("h3", {
+                        className: "font-semibold",
+                        children: "Partial imports"
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV6("p", {
+                        className: "text-muted-foreground text-sm",
+                        children: [
+                          "Some endpoints may not be detected if they use unconventional patterns. Use ",
+                          /* @__PURE__ */ jsxDEV6("code", {
+                            children: "--analyze"
+                          }, undefined, false, undefined, this),
+                          " to see what was found, then add missing contracts manually."
+                        ]
+                      }, undefined, true, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6(StudioPrompt, {
+            title: "Want automated contract evolution?",
+            body: "Studio monitors your codebase and suggests contract updates when your API changes, keeping specs and code in sync."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV6("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV6(Link6, {
+            href: "/docs/guides/spec-validation-and-typing",
+            className: "btn-primary",
+            children: [
+              "Next: Spec validation + typing ",
+              /* @__PURE__ */ jsxDEV6(ChevronRight5, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV6(Link6, {
+            href: "/docs/guides",
+            className: "btn-ghost",
+            children: "Back to guides"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideNextjsOneEndpointPage.tsx
+import { CodeBlock as CodeBlock6 } from "@contractspec/lib.design-system";
+import Link7 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight6 } from "lucide-react";
+import { jsxDEV as jsxDEV7 } from "react/jsx-dev-runtime";
+function GuideNextjsOneEndpointPage() {
+  return /* @__PURE__ */ jsxDEV7("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV7("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV7("h1", {
+            className: "text-4xl font-bold",
+            children: "Next.js: add one endpoint"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV7("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Add ContractSpec to an existing Next.js App Router project by wiring a single operation end-to-end with validation and types."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV7("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV7("h2", {
+            className: "text-2xl font-bold",
+            children: "What you'll build"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV7("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV7("li", {
+                children: "One OperationSpec with SchemaModel validation."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("li", {
+                children: "A registry wiring the operation to its handler."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("li", {
+                children: "A Next.js route handler that exposes the operation."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV7("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV7("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV7("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Install core packages"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7(CodeBlock6, {
+                language: "bash",
+                filename: "nextjs-install",
+                code: `bun add -D contractspec
+bun add @contractspec/lib.contracts @contractspec/lib.schema`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: ",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: "added 3 packages"
+                  }, undefined, false, undefined, this),
+                  " and a lockfile update."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV7("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Define the operation spec"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Create ",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: "src/contracts/healthcheck.operation.ts"
+                  }, undefined, false, undefined, this),
+                  ":"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV7(CodeBlock6, {
+                language: "typescript",
+                filename: "src/contracts/healthcheck.operation.ts",
+                code: `import { defineQuery } from "@contractspec/lib.contracts/operations";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+const HealthcheckOutput = new SchemaModel({
+  name: "HealthcheckOutput",
+  fields: {
+    status: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    checkedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const HealthcheckQuery = defineQuery({
+  meta: {
+    key: "healthcheck.get",
+    version: "1.0.0",
+    description: "Return service health status",
+    owners: ["@platform.core"],
+    tags: ["health", "observability"],
+  },
+  io: {
+    input: null,
+    output: HealthcheckOutput,
+  },
+  policy: {
+    auth: "public",
+  },
+  transport: {
+    rest: { method: "GET" },
+    gql: { field: "healthcheck_get" },
+    mcp: { toolName: "healthcheck.get.v1" },
+  },
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV7("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Register the operation"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Create ",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: "src/contracts/registry.ts"
+                  }, undefined, false, undefined, this),
+                  ":"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV7(CodeBlock6, {
+                language: "typescript",
+                filename: "src/contracts/registry.ts",
+                code: `import {
+  OperationSpecRegistry,
+  installOp,
+} from "@contractspec/lib.contracts/operations";
+import { HealthcheckQuery } from "./healthcheck.operation";
+
+export const registry = new OperationSpecRegistry();
+
+installOp(registry, HealthcheckQuery, async () => ({
+  status: "ok",
+  checkedAt: new Date().toISOString(),
+}));`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV7("h2", {
+                className: "text-2xl font-bold",
+                children: "4) Add the Next.js handler"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Create ",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: "app/api/ops/[...route]/route.ts"
+                  }, undefined, false, undefined, this),
+                  ":"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV7(CodeBlock6, {
+                language: "typescript",
+                filename: "app/api/ops/[...route]/route.ts",
+                code: `import { makeNextAppHandler } from "@contractspec/lib.contracts/server/rest-next-app";
+import { registry } from "@/contracts/registry";
+
+const handler = makeNextAppHandler(registry, async () => ({
+  actor: "public",
+  tenantId: "public",
+}));
+
+export { handler as GET, handler as POST };`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: the route responds at",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: " /api/ops/healthcheck.get"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV7("h2", {
+                className: "text-2xl font-bold",
+                children: "5) Validate the spec"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7(CodeBlock6, {
+                language: "bash",
+                filename: "nextjs-validate",
+                code: `contractspec validate src/contracts/healthcheck.operation.ts`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: ",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: "Validation passed"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7("div", {
+            className: "card-subtle space-y-3 p-6",
+            children: [
+              /* @__PURE__ */ jsxDEV7("h3", {
+                className: "text-lg font-semibold",
+                children: "Example package"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV7("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Use ",
+                  /* @__PURE__ */ jsxDEV7("code", {
+                    children: "@contractspec/example.lifecycle-dashboard"
+                  }, undefined, false, undefined, this),
+                  " as a lightweight Next.js snippet reference."
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV7(CodeBlock6, {
+                language: "bash",
+                filename: "nextjs-example",
+                code: `# Inspect the example docs
+contractspec examples show lifecycle-dashboard
+
+# Validate all example manifests in this repo
+contractspec examples validate --repo-root .`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7(StudioPrompt, {
+            title: "Need team approvals for new endpoints?",
+            body: "Studio adds review gates, shared registries, and audit trails after you ship your first endpoint."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV7("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV7(Link7, {
+            href: "/docs/guides/spec-validation-and-typing",
+            className: "btn-primary",
+            children: [
+              "Next: Spec validation + typing ",
+              /* @__PURE__ */ jsxDEV7(ChevronRight6, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV7(Link7, {
+            href: "/docs/guides",
+            className: "btn-ghost",
+            children: "Back to guides"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuideSpecValidationTypingPage.tsx
+import { CodeBlock as CodeBlock7 } from "@contractspec/lib.design-system";
+import Link8 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight7 } from "lucide-react";
+import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
+function GuideSpecValidationTypingPage() {
+  return /* @__PURE__ */ jsxDEV8("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV8("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV8("h1", {
+            className: "text-4xl font-bold",
+            children: "Spec-driven validation + typing"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV8("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Define a single operation with SchemaModel, generate validation, and keep your existing handler logic."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV8("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV8("h2", {
+            className: "text-2xl font-bold",
+            children: "What you'll build"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV8("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV8("li", {
+                children: "One command spec with explicit input/output models."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8("li", {
+                children: "Validation + typing without rewriting your service layer."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8("li", {
+                children: "Clear acceptance scenarios for regression safety."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV8("div", {
+        className: "space-y-6",
+        children: [
+          /* @__PURE__ */ jsxDEV8("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV8("h2", {
+                className: "text-2xl font-bold",
+                children: "1) Define the spec"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Create ",
+                  /* @__PURE__ */ jsxDEV8("code", {
+                    children: "src/contracts/contact-create.operation.ts"
+                  }, undefined, false, undefined, this),
+                  ":"
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV8(CodeBlock7, {
+                language: "typescript",
+                filename: "src/contracts/contact-create.operation.ts",
+                code: `import { defineCommand } from "@contractspec/lib.contracts/operations";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+const ContactInput = new SchemaModel({
+  name: "ContactInput",
+  fields: {
+    email: { type: ScalarTypeEnum.Email(), isOptional: false },
+    firstName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    lastName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+  },
+});
+
+const ContactOutput = new SchemaModel({
+  name: "ContactOutput",
+  fields: {
+    id: { type: ScalarTypeEnum.String(), isOptional: false },
+    email: { type: ScalarTypeEnum.Email(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const ContactCreateCommand = defineCommand({
+  meta: {
+    key: "contact.create",
+    version: "1.0.0",
+    description: "Create a CRM contact",
+    owners: ["@sales"],
+    tags: ["crm", "contacts"],
+  },
+  io: {
+    input: ContactInput,
+    output: ContactOutput,
+  },
+  policy: {
+    auth: "user",
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "create-contact",
+        given: ["User is authenticated"],
+        when: ["ContactCreateCommand executes"],
+        then: ["Contact is persisted", "Email is validated"],
+      },
+    ],
+  },
+});`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV8("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV8("h2", {
+                className: "text-2xl font-bold",
+                children: "2) Wire the handler"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8("p", {
+                className: "text-muted-foreground text-sm",
+                children: "Keep your existing code. Just ensure the handler returns the output shape defined above."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8(CodeBlock7, {
+                language: "typescript",
+                filename: "src/handlers/contact-create.ts",
+                code: `import { ContactCreateCommand } from "@/contracts/contact-create.operation";
+ 
+ export async function handleContactCreate(
+   input: (typeof ContactCreateCommand)["io"]["input"],
+   ctx: { userId: string }
+ ) {
+   // Your existing persistence logic
+   return {
+     id: "contact_123",
+     email: input.email,
+     createdAt: new Date().toISOString(),
+   };
+ }`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV8("div", {
+            className: "space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV8("h2", {
+                className: "text-2xl font-bold",
+                children: "3) Validate"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8(CodeBlock7, {
+                language: "bash",
+                filename: "spec-validation",
+                code: `contractspec validate src/contracts/contact-create.operation.ts`
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8("p", {
+                className: "text-muted-foreground text-sm",
+                children: [
+                  "Expected output: ",
+                  /* @__PURE__ */ jsxDEV8("code", {
+                    children: "Validation passed"
+                  }, undefined, false, undefined, this),
+                  "."
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV8("div", {
+            className: "card-subtle space-y-3 p-6",
+            children: [
+              /* @__PURE__ */ jsxDEV8("h3", {
+                className: "text-lg font-semibold",
+                children: "Example package"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8("p", {
+                className: "text-muted-foreground text-sm",
+                children: "The CRM Pipeline example includes real specs, handlers, and presentations for contact + deal flows."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV8(CodeBlock7, {
+                language: "bash",
+                filename: "crm-example",
+                code: `# Build + validate the CRM pipeline example
+cd packages/examples/crm-pipeline
+bun install
+bun run build
+bun run validate`
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV8(StudioPrompt, {
+            title: "Need shared validation policies?",
+            body: "Studio lets teams enforce validation policies and review changes before they ship."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV8("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV8(Link8, {
+            href: "/docs/guides/generate-docs-clients-schemas",
+            className: "btn-primary",
+            children: [
+              "Next: Generate docs + clients ",
+              /* @__PURE__ */ jsxDEV8(ChevronRight7, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV8(Link8, {
+            href: "/docs/guides",
+            className: "btn-ghost",
+            children: "Back to guides"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/GuidesIndexPage.tsx
+import { CodeBlock as CodeBlock8 } from "@contractspec/lib.design-system";
+import Link9 from "@contractspec/lib.ui-link";
+import { ArrowRight, BookOpen, CheckCircle2 } from "lucide-react";
+import { jsxDEV as jsxDEV9 } from "react/jsx-dev-runtime";
+var 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"
+  }
+];
+function GuidesIndexPage() {
+  return /* @__PURE__ */ jsxDEV9("div", {
+    className: "space-y-10",
+    children: [
+      /* @__PURE__ */ jsxDEV9("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsxDEV9("h1", {
+            className: "text-4xl font-bold",
+            children: "Guides"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV9("p", {
+            className: "text-muted-foreground text-lg",
+            children: "Hands-on guides with commands, expected output, and CI-verified example packages."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV9("div", {
+        className: "grid gap-4 md:grid-cols-2",
+        children: guides.map((guide) => /* @__PURE__ */ jsxDEV9(Link9, {
+          href: guide.href,
+          className: "card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50",
+          children: [
+            /* @__PURE__ */ jsxDEV9("div", {
+              className: "flex items-center justify-between",
+              children: [
+                /* @__PURE__ */ jsxDEV9("h2", {
+                  className: "text-xl font-semibold transition-colors group-hover:text-violet-400",
+                  children: guide.title
+                }, undefined, false, undefined, this),
+                /* @__PURE__ */ jsxDEV9(ArrowRight, {
+                  className: "text-violet-400",
+                  size: 18
+                }, undefined, false, undefined, this)
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV9("p", {
+              className: "text-muted-foreground text-sm",
+              children: guide.description
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV9("div", {
+              className: "text-muted-foreground flex items-center gap-2 text-xs",
+              children: [
+                /* @__PURE__ */ jsxDEV9(CheckCircle2, {
+                  size: 14
+                }, undefined, false, undefined, this),
+                /* @__PURE__ */ jsxDEV9("span", {
+                  children: [
+                    "Target time: ",
+                    guide.time
+                  ]
+                }, undefined, true, undefined, this)
+              ]
+            }, undefined, true, undefined, this)
+          ]
+        }, guide.href, true, undefined, this))
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV9("div", {
+        className: "card-subtle space-y-4 p-6",
+        children: [
+          /* @__PURE__ */ jsxDEV9("div", {
+            className: "flex items-center gap-2 text-sm font-semibold tracking-[0.2em] text-violet-400 uppercase",
+            children: [
+              /* @__PURE__ */ jsxDEV9(BookOpen, {
+                size: 16
+              }, undefined, false, undefined, this),
+              "How to use the guides"
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV9("ul", {
+            className: "text-muted-foreground space-y-2 text-sm",
+            children: [
+              /* @__PURE__ */ jsxDEV9("li", {
+                children: "Run each guide in a fresh branch or sandbox workspace."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV9("li", {
+                children: "Use the linked example package to validate end-to-end."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV9("li", {
+                children: "Keep the commands as written to match CI expectations."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV9(CodeBlock8, {
+            language: "bash",
+            filename: "guides-quickstart",
+            code: `# list all examples
+contractspec examples list
+
+# validate example packages in this repo
+contractspec examples validate --repo-root .`
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/components/docs/guides/guides.docblocks.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var guideDocBlocks = [
+  {
+    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)
+
+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
+
+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
+
+Use ContractSpec to generate documentation and OpenAPI exports for client SDKs.
+
+## Generate reference docs
+
+1. Regenerate contract artifacts:
+
+\`\`\`bash
+bun contractspec generate
+\`\`\`
+
+2. Build docs output (index + markdown):
+
+\`\`\`bash
+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
+
+Use ContractSpec to generate reference markdown, build a chunked index, and wire it into your docs routes.
+
+## Generate contract docs
+
+\`\`\`bash
+contractspec generate
+\`\`\`
+
+## Build the docs index
+
+\`\`\`bash
+bun docs:generate
+# versioned output
+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
+
+Run ContractSpec CI checks to detect drift and breaking changes before merge.`
+  }
+];
+registerDocBlocks(guideDocBlocks);
+export {
+  GuidesIndexPage,
+  GuideSpecValidationTypingPage,
+  GuideNextjsOneEndpointPage,
+  GuideImportExistingCodebasesPage,
+  GuideGenerateDocsClientsSchemasPage,
+  GuideDocsPipelinePage,
+  GuideContractTypesPage,
+  GuideCIDiffGatingPage
+};