@contractspec/bundle.library 3.10.1 → 3.10.2

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

@@ -1,6 +1,6 @@
-var Le=Object.defineProperty;var We=(o)=>o;function Fe(o,O){this[o]=We.bind(null,O)}var Jt=(o,O)=>{for(var z in O)Le(o,z,{get:O[z],enumerable:!0,configurable:!0,set:Fe.bind(O,z)})};var Yt=(o,O)=>()=>(o&&(O=o(o=0)),O);import qe from"@contractspec/lib.ui-link";import{jsx as ae,jsxs as Ge}from"react/jsx-runtime";function v({title:o="Need the operating layer on top of OSS ContractSpec?",body:O="ContractSpec Studio helps teams turn evidence into proposed spec changes, governed delivery loops, and execution-ready task packs while keeping the open contract system as the source of truth.",ctaLabel:z="See what Studio adds",href:Ue="https://www.contractspec.studio/docs"}){return Ge("div",{className:"card-subtle space-y-3 p-6",children:[ae("h3",{className:"font-semibold text-lg",children:o}),ae("p",{className:"text-muted-foreground text-sm",children:O}),ae(qe,{href:Ue,className:"btn-primary",children:z})]})}import{CodeBlock as X}from"@contractspec/lib.design-system";import pe from"@contractspec/lib.ui-link";import{ChevronRight as ze}from"lucide-react";import{jsx as m,jsxs as A}from"react/jsx-runtime";function _e(){return A("div",{className:"space-y-8",children:[A("div",{className:"space-y-3",children:[m("h1",{className:"font-bold text-4xl",children:"CI gating with deterministic diffs"}),m("p",{className:"text-lg text-muted-foreground",children:"Add ContractSpec CI checks that validate specs, detect drift, and gate breaking changes before merge."})]}),A("div",{className:"card-subtle space-y-4 p-6",children:[m("h2",{className:"font-bold text-2xl",children:"What you'll build"}),A("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[m("li",{children:"CI workflow running ContractSpec validation and drift checks."}),m("li",{children:"Machine-readable output for PR annotations."}),m("li",{children:"Deterministic contract diffs in review."})]})]}),A("div",{className:"space-y-6",children:[A("div",{className:"space-y-3",children:[m("h2",{className:"font-bold text-2xl",children:"1) Add the CI workflow"}),m("p",{className:"text-muted-foreground text-sm",children:"Copy the template from the CLI package."}),m(X,{language:"bash",filename:"ci-copy",code:"cp node_modules/@contractspec/app.cli-contractspec/templates/github-action.yml .github/workflows/contractspec.yml"}),A("p",{className:"text-muted-foreground text-sm",children:["Expected output: new workflow file in ",m("code",{children:".github/workflows"}),"."]})]}),A("div",{className:"space-y-3",children:[m("h2",{className:"font-bold text-2xl",children:"2) Run CI locally"}),m(X,{language:"bash",filename:"ci-local",code:"contractspec ci --format json --check-drift"}),m("p",{className:"text-muted-foreground text-sm",children:"Expected output: JSON summary including pass/fail counts and drift status (if configured)."})]}),A("div",{className:"space-y-3",children:[m("h2",{className:"font-bold text-2xl",children:"3) Add a diff check"}),m("p",{className:"text-muted-foreground text-sm",children:"Use the diff command to inspect breaking changes in PRs."}),m(X,{language:"bash",filename:"ci-diff",code:"contractspec diff src/contracts/spec-v1.ts src/contracts/spec-v2.ts --breaking"}),m("p",{className:"text-muted-foreground text-sm",children:"Expected output: deterministic diff with breaking change hints."})]}),A("div",{className:"card-subtle space-y-3 p-6",children:[m("h3",{className:"font-semibold text-lg",children:"Example package"}),m("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."}),m(X,{language:"bash",filename:"crm-ci",code:`cd packages/examples/crm-pipeline
+var qe=Object.defineProperty;var Fe=(o)=>o;function ze(o,T){this[o]=Fe.bind(null,T)}var xt=(o,T)=>{for(var K in T)qe(o,K,{get:T[K],enumerable:!0,configurable:!0,set:ze.bind(T,K)})};var jt=(o,T)=>()=>(o&&(T=o(o=0)),T);import Ke from"@contractspec/lib.ui-link";import{jsx as ne,jsxs as Qe}from"react/jsx-runtime";function N({title:o="Need the operating layer on top of OSS ContractSpec?",body:T="ContractSpec Studio helps teams turn evidence into proposed spec changes, governed delivery loops, and execution-ready task packs while keeping the open contract system as the source of truth.",ctaLabel:K="See what Studio adds",href:_e="https://www.contractspec.studio/docs"}){return Qe("div",{className:"card-subtle space-y-3 p-6",children:[ne("h3",{className:"font-semibold text-lg",children:o}),ne("p",{className:"text-muted-foreground text-sm",children:T}),ne(Ke,{href:_e,className:"btn-primary",children:K})]})}import{CodeBlock as V}from"@contractspec/lib.design-system";import he from"@contractspec/lib.ui-link";import{ChevronRight as Je}from"lucide-react";import{jsx as m,jsxs as R}from"react/jsx-runtime";function Ye(){return R("div",{className:"space-y-8",children:[R("div",{className:"space-y-3",children:[m("h1",{className:"font-bold text-4xl",children:"CI gating with deterministic diffs"}),m("p",{className:"text-lg text-muted-foreground",children:"Add ContractSpec CI checks that validate specs, detect drift, and gate breaking changes before merge."})]}),R("div",{className:"card-subtle space-y-4 p-6",children:[m("h2",{className:"font-bold text-2xl",children:"What you'll build"}),R("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[m("li",{children:"CI workflow running ContractSpec validation and drift checks."}),m("li",{children:"Machine-readable output for PR annotations."}),m("li",{children:"Deterministic contract diffs in review."})]})]}),R("div",{className:"space-y-6",children:[R("div",{className:"space-y-3",children:[m("h2",{className:"font-bold text-2xl",children:"1) Add the CI workflow"}),m("p",{className:"text-muted-foreground text-sm",children:"Copy the template from the CLI package."}),m(V,{language:"bash",filename:"ci-copy",code:"cp node_modules/@contractspec/app.cli-contractspec/templates/github-action.yml .github/workflows/contractspec.yml"}),R("p",{className:"text-muted-foreground text-sm",children:["Expected output: new workflow file in ",m("code",{children:".github/workflows"}),"."]})]}),R("div",{className:"space-y-3",children:[m("h2",{className:"font-bold text-2xl",children:"2) Run CI locally"}),m(V,{language:"bash",filename:"ci-local",code:"contractspec ci --format json --check-drift"}),m("p",{className:"text-muted-foreground text-sm",children:"Expected output: JSON summary including pass/fail counts and drift status (if configured)."})]}),R("div",{className:"space-y-3",children:[m("h2",{className:"font-bold text-2xl",children:"3) Add a diff check"}),m("p",{className:"text-muted-foreground text-sm",children:"Use the diff command to inspect breaking changes in PRs."}),m(V,{language:"bash",filename:"ci-diff",code:"contractspec diff src/contracts/spec-v1.ts src/contracts/spec-v2.ts --breaking"}),m("p",{className:"text-muted-foreground text-sm",children:"Expected output: deterministic diff with breaking change hints."})]}),R("div",{className:"card-subtle space-y-3 p-6",children:[m("h3",{className:"font-semibold text-lg",children:"Example package"}),m("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."}),m(V,{language:"bash",filename:"crm-ci",code:`cd packages/examples/crm-pipeline
 bun run build
-bun run validate`})]}),m(v,{title:"Need continuous checks tied to outcomes?",body:"Studio closes the loop with post-change verification and learning dividends that improve future decisions."})]}),A("div",{className:"flex items-center gap-4 pt-4",children:[A(pe,{href:"/docs/guides",className:"btn-primary",children:["Back to guides ",m(ze,{size:16})]}),m(pe,{href:"/docs",className:"btn-ghost",children:"Docs home"})]})]})}import{CodeBlock as L}from"@contractspec/lib.design-system";import me from"@contractspec/lib.ui-link";import{ChevronRight as Ke}from"lucide-react";import{jsx as c,jsxs as C}from"react/jsx-runtime";var Qe=[".contractspec/connect/context-pack.json",".contractspec/connect/plan-packet.json",".contractspec/connect/patch-verdict.json",".contractspec/connect/audit.ndjson",".contractspec/connect/decisions/<decisionId>/",".contractspec/adoption/catalog.json",".contractspec/adoption/overrides.json"];function Je(){return C("div",{className:"space-y-8",children:[C("div",{className:"space-y-3",children:[c("h1",{className:"font-bold text-4xl",children:"Use Connect in a repo"}),c("p",{className:"text-lg text-muted-foreground",children:"Put coding-agent edits and shell commands behind task-scoped context, plan compilation, verification, and local review evidence without introducing a second control plane."})]}),C("div",{className:"card-subtle space-y-4 p-6",children:[c("h2",{className:"font-bold text-2xl",children:"What you'll build"}),C("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[c("li",{children:"A workspace-level Connect config in `.contractsrc.json`."}),c("li",{children:"A reuse-first adoption check before new implementation work."}),c("li",{children:"A context and plan flow for one task."}),c("li",{children:"Verified file and shell mutations with local review/replay evidence."})]})]}),C("div",{className:"space-y-6",children:[C("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"1) Enable Connect"}),c("p",{className:"text-muted-foreground text-sm",children:"Start by making the safety policy explicit. Protected paths, generated paths, review thresholds, and command rules live in the workspace config, not in editor-specific hooks."}),c(L,{language:"json",filename:".contractsrc.json",code:`{
+bun run validate`})]}),m(N,{title:"Need continuous checks tied to outcomes?",body:"Studio closes the loop with post-change verification and learning dividends that improve future decisions."})]}),R("div",{className:"flex items-center gap-4 pt-4",children:[R(he,{href:"/docs/guides",className:"btn-primary",children:["Back to guides ",m(Je,{size:16})]}),m(he,{href:"/docs",className:"btn-ghost",children:"Docs home"})]})]})}import{CodeBlock as W}from"@contractspec/lib.design-system";import fe from"@contractspec/lib.ui-link";import{ChevronRight as $e}from"lucide-react";import{jsx as c,jsxs as S}from"react/jsx-runtime";var Xe=[".contractspec/connect/context-pack.json",".contractspec/connect/plan-packet.json",".contractspec/connect/patch-verdict.json",".contractspec/connect/audit.ndjson",".contractspec/connect/decisions/<decisionId>/",".contractspec/adoption/catalog.json",".contractspec/adoption/overrides.json"];function Ze(){return S("div",{className:"space-y-8",children:[S("div",{className:"space-y-3",children:[c("h1",{className:"font-bold text-4xl",children:"Use Connect in a repo"}),c("p",{className:"text-lg text-muted-foreground",children:"Put coding-agent edits and shell commands behind task-scoped context, plan compilation, verification, and local review evidence without introducing a second control plane."})]}),S("div",{className:"card-subtle space-y-4 p-6",children:[c("h2",{className:"font-bold text-2xl",children:"What you'll build"}),S("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[c("li",{children:"A workspace-level Connect config in `.contractsrc.json`."}),c("li",{children:"A reuse-first adoption check before new implementation work."}),c("li",{children:"A context and plan flow for one task."}),c("li",{children:"Verified file and shell mutations with local review/replay evidence."})]})]}),S("div",{className:"space-y-6",children:[S("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"1) Enable Connect"}),c("p",{className:"text-muted-foreground text-sm",children:"Start by making the safety policy explicit. Protected paths, generated paths, review thresholds, and command rules live in the workspace config, not in editor-specific hooks."}),c(W,{language:"json",filename:".contractsrc.json",code:`{
   "connect": {
     "enabled": true,
     "storage": {
@@ -49,25 +49,25 @@ bun run validate`})]}),m(v,{title:"Need continuous checks tied to outcomes?",bod
       }
     }
   }
-}`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: Connect has enough policy to classify writes, commands, drift, and review thresholds deterministically."})]}),C("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"2) Initialize storage"}),c(L,{language:"bash",filename:"connect-init",code:"contractspec connect init --scope workspace"}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: `.contractsrc.json` is updated if needed and `.contractspec/connect/` is created."})]}),C("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"3) Mirror the adoption catalog and resolve reuse first"}),c("p",{className:"text-muted-foreground text-sm",children:"Connect adoption is the reuse-first layer for authoring. Mirror the local catalog, then resolve the best existing surface for the family you are about to touch before you scaffold or invent anything new."}),c(L,{language:"bash",filename:"connect-adoption",code:`contractspec connect adoption sync --json
+}`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: Connect has enough policy to classify writes, commands, drift, and review thresholds deterministically."})]}),S("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"2) Initialize storage"}),c(W,{language:"bash",filename:"connect-init",code:"contractspec connect init --scope workspace"}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: `.contractsrc.json` is updated if needed and `.contractspec/connect/` is created."})]}),S("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"3) Mirror the adoption catalog and resolve reuse first"}),c("p",{className:"text-muted-foreground text-sm",children:"Connect adoption is the reuse-first layer for authoring. Mirror the local catalog, then resolve the best existing surface for the family you are about to touch before you scaffold or invent anything new."}),c(W,{language:"bash",filename:"connect-adoption",code:`contractspec connect adoption sync --json
 
 printf '{"goal":"Prefer an existing release helper before adding a new one"}' | \\
-  contractspec connect adoption resolve --family sharedLibs --stdin --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: a mirrored local adoption catalog plus a reuse recommendation that can point to an existing workspace package or a ContractSpec surface before the task reaches file mutation."})]}),C("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"4) Project context and compile a plan"}),c("p",{className:"text-muted-foreground text-sm",children:"Use the task id as the thread that connects context, plan, verdict, and replay artifacts."}),c(L,{language:"bash",filename:"connect-plan",code:`contractspec connect context \\
+  contractspec connect adoption resolve --family sharedLibs --stdin --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: a mirrored local adoption catalog plus a reuse recommendation that can point to an existing workspace package or a ContractSpec surface before the task reaches file mutation."})]}),S("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"4) Project context and compile a plan"}),c("p",{className:"text-muted-foreground text-sm",children:"Use the task id as the thread that connects context, plan, verdict, and replay artifacts."}),c(W,{language:"bash",filename:"connect-plan",code:`contractspec connect context \\
   --task docs-connect \\
   --paths packages/libs/contracts-spec/src/control-plane/contracts.ts \\
   --json
 
 printf '{"objective":"Document the control-plane contract surface","commands":["bun run typecheck"]}' | \\
-  contractspec connect plan --task docs-connect --stdin --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: a `ContextPack` and `PlanPacket` that point back to `controlPlane.intent.submit`, `controlPlane.plan.compile`, and `controlPlane.plan.verify`."})]}),C("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"5) Verify file and shell mutations"}),c(L,{language:"bash",filename:"connect-verify",code:`printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | \\
+  contractspec connect plan --task docs-connect --stdin --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: a `ContextPack` and `PlanPacket` that point back to `controlPlane.intent.submit`, `controlPlane.plan.compile`, and `controlPlane.plan.verify`."})]}),S("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"5) Verify file and shell mutations"}),c(W,{language:"bash",filename:"connect-verify",code:`printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | \\
   contractspec connect verify --task docs-connect --tool acp.fs.access --stdin --json
 
 printf 'bun run typecheck' | \\
-  contractspec connect verify --task docs-connect --tool acp.terminal.exec --stdin --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: a `PatchVerdict` with `permit`, `rewrite`, `require_review`, or `deny`, plus a runtime-linked control-plane state when that linkage is available."})]}),C("div",{className:"card-subtle space-y-3 p-6",children:[c("h3",{className:"font-semibold text-lg",children:"Artifacts to inspect"}),c("ul",{className:"space-y-2 text-muted-foreground text-sm",children:Qe.map((o)=>c("li",{children:c("code",{children:o})},o))})]}),C("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"6) Review, replay, and optional Studio sync"}),c(L,{language:"bash",filename:"connect-review-replay",code:`contractspec connect review list --json
+  contractspec connect verify --task docs-connect --tool acp.terminal.exec --stdin --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Expected output: a `PatchVerdict` with `permit`, `rewrite`, `require_review`, or `deny`, plus a runtime-linked control-plane state when that linkage is available."})]}),S("div",{className:"card-subtle space-y-3 p-6",children:[c("h3",{className:"font-semibold text-lg",children:"Artifacts to inspect"}),c("ul",{className:"space-y-2 text-muted-foreground text-sm",children:Xe.map((o)=>c("li",{children:c("code",{children:o})},o))})]}),S("div",{className:"space-y-3",children:[c("h2",{className:"font-bold text-2xl",children:"6) Review, replay, and optional Studio sync"}),c(W,{language:"bash",filename:"connect-review-replay",code:`contractspec connect review list --json
 contractspec connect replay <decisionId> --json
 contractspec connect eval <decisionId> --registry ./harness-registry.ts --scenario connect.safe-refactor --json
 
 # Optional when Studio review-bridge mode is enabled
-contractspec connect review sync --decision <decisionId> --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Local review packets remain authoritative. Studio sync is an operator convenience layer, not a requirement for baseline OSS safety."})]})]}),C("div",{className:"flex items-center gap-4 pt-4",children:[C(me,{href:"/docs/specs/connect",className:"btn-primary",children:["Back to Connect spec ",c(Ke,{size:16})]}),c(me,{href:"/docs/architecture/control-plane",className:"btn-ghost",children:"Control-plane runtime"})]})]})}var ue=`import {
+contractspec connect review sync --decision <decisionId> --json`}),c("p",{className:"text-muted-foreground text-sm",children:"Local review packets remain authoritative. Studio sync is an operator convenience layer, not a requirement for baseline OSS safety."})]})]}),S("div",{className:"flex items-center gap-4 pt-4",children:[S(fe,{href:"/docs/specs/connect",className:"btn-primary",children:["Back to Connect spec ",c($e,{size:16})]}),c(fe,{href:"/docs/architecture/control-plane",className:"btn-ghost",children:"Control-plane runtime"})]})]})}var ge=`import {
   defineFormSpec,
   FormRegistry,
   responsiveFormColumns,
@@ -133,7 +133,7 @@ export const LeadCaptureForm = defineFormSpec({
   renderHints: { ui: "shadcn", form: "react-hook-form" },
 });
 
-export const formRegistry = new FormRegistry().register(LeadCaptureForm);`,he=`"use client";
+export const formRegistry = new FormRegistry().register(LeadCaptureForm);`,ye=`"use client";
 
 import { formRenderer } from "@contractspec/lib.design-system/renderers/form-contract";
 import { LeadCaptureForm } from "../contracts/forms/lead-capture.form";
@@ -151,7 +151,7 @@ export function LeadCapturePanel() {
       },
     },
   });
-}`,fe=`bun add @contractspec/example.form-showcase
+}`,ve=`bun add @contractspec/example.form-showcase
 
 # Full form-only example docs
 open https://www.contractspec.io/docs/examples/form-showcase
@@ -160,7 +160,7 @@ open https://www.contractspec.io/docs/examples/form-showcase
 open https://www.contractspec.io/templates?tag=forms
 
 # Sandbox spec preview
-open https://www.contractspec.io/sandbox?template=form-showcase`;import{CodeBlock as _}from"@contractspec/lib.design-system";import{HStack as Ye,VStack as B}from"@contractspec/lib.design-system/layout";import{List as $e,ListItem as oe}from"@contractspec/lib.design-system/list";import{Code as ge,H1 as Xe,H2 as Z,H3 as ye,P as W,Text as K}from"@contractspec/lib.design-system/typography";import H from"@contractspec/lib.ui-link";import{ChevronRight as Ze}from"lucide-react";import{jsx as l,jsxs as w}from"react/jsx-runtime";function He(){return w(B,{className:"space-y-8",children:[w(B,{className:"space-y-3",children:[l(Xe,{className:"font-bold text-4xl",children:"Build a contract-driven form"}),l(W,{className:"text-lg text-muted-foreground",children:"Define form data, fields, layout, policy, and submit behavior once, then let your app render from the same ContractSpec surface."})]}),w(B,{className:"card-subtle space-y-4 p-6",children:[l(Z,{className:"font-bold text-2xl",children:"What you'll build"}),w($e,{className:"space-y-2 text-muted-foreground text-sm",children:[l(oe,{children:l(K,{children:"A schema-backed FormSpec for a lead capture form."})}),l(oe,{children:l(K,{children:"A FormRegistry that exposes the latest version by stable key."})}),l(oe,{children:l(K,{children:"A React renderer that keeps UI, validation, and policy aligned."})})]})]}),w(B,{className:"space-y-6",children:[w(B,{className:"space-y-3",children:[l(Z,{className:"font-bold text-2xl",children:"1) Define the form spec"}),w(W,{className:"text-muted-foreground text-sm",children:["Create ",l(ge,{children:"src/contracts/forms/lead-capture.form.ts"}),":"]}),l(_,{language:"typescript",filename:"src/contracts/forms/lead-capture.form.ts",code:ue})]}),w(B,{className:"card-subtle space-y-3 p-6",children:[l(ye,{className:"font-semibold text-lg",children:"Need every form field?"}),w(W,{className:"text-muted-foreground text-sm",children:["Start from the"," ",l(H,{href:"/docs/examples/form-showcase",children:"Form Showcase example"})," ","or the"," ",l(H,{href:"/templates?tag=forms",children:"form template catalog"}),". It is focused only on forms and covers field kinds, section layouts, step layouts, arrays, groups, conditionals, and validation hints."]}),l(_,{language:"bash",filename:"form-showcase-template",code:fe})]}),w(B,{className:"space-y-3",children:[l(Z,{className:"font-bold text-2xl",children:"2) Render from the contract"}),l(W,{className:"text-muted-foreground text-sm",children:"Use the shared renderer, or provide your own driver if your app uses a different component library."}),l(_,{language:"tsx",filename:"src/components/LeadCapturePanel.tsx",code:he})]}),w(B,{className:"space-y-3",children:[l(Z,{className:"font-bold text-2xl",children:"3) Validate and evolve"}),l(_,{language:"bash",filename:"validate-form",code:"contractspec validate src/contracts/forms/lead-capture.form.ts"}),w(W,{className:"text-muted-foreground text-sm",children:["Expected output: ",l(ge,{children:"Validation passed"}),". When the form becomes public contract surface, version changes deliberately instead of editing field meaning in place."]})]}),w(B,{className:"card-subtle space-y-3 p-6",children:[l(ye,{className:"font-semibold text-lg",children:"Repo tutorial"}),l(W,{className:"text-muted-foreground text-sm",children:"The repository guide adds the longer implementation checklist, custom renderer notes, and rollout rules."}),l(_,{language:"bash",filename:"repo-guide",code:"open docs/tutorials/contract-driven-forms.md"})]}),l(v,{title:"Need governed form changes?",body:"Studio can connect form edits to customer evidence, approval packets, and rollout checks before teams regenerate public surfaces."})]}),w(Ye,{className:"flex items-center gap-4 pt-4",children:[w(H,{href:"/docs/guides/generate-docs-clients-schemas",className:"btn-primary",children:[l(K,{children:"Next: Generate docs + clients"}),l(Ze,{size:16})]}),l(H,{href:"/docs/guides",className:"btn-ghost",children:l(K,{children:"Back to guides"})})]})]})}import{CodeBlock as Q}from"@contractspec/lib.design-system";import be from"@contractspec/lib.ui-link";import{ChevronRight as Ve,Globe as xe,Layers as je,Shield as et,Zap as tt}from"lucide-react";import{jsx as t,jsxs as i}from"react/jsx-runtime";var at=[{name:"Operations",factory:"defineCommand / defineQuery",description:"API endpoints with input/output schemas, validation, and policy.",icon:tt,color:"text-blue-400"},{name:"Events",factory:"defineEvent",description:"Domain events with typed payloads and PII handling.",icon:je,color:"text-green-400"},{name:"Capabilities",factory:"defineCapability",description:"Feature groupings that link operations, events, and UIs.",icon:et,color:"text-purple-400"},{name:"Presentations",factory:"definePresentation",description:"UI specifications for rendering data and handling interactions.",icon:xe,color:"text-orange-400"}];function ot(){return i("div",{className:"space-y-8",children:[i("div",{className:"space-y-3",children:[t("h1",{className:"font-bold text-4xl",children:"Contract Types Overview"}),t("p",{className:"text-lg text-muted-foreground",children:"Learn about the different contract types in ContractSpec and when to use each one when you are making the system boundary explicit."})]}),i("div",{className:"card-subtle space-y-4 p-6",children:[t("h2",{className:"font-bold text-2xl",children:"Core Contract Types"}),t("div",{className:"grid gap-3 md:grid-cols-2",children:at.map((o)=>i("div",{className:"flex items-start gap-3 rounded-lg border border-white/10 p-4",children:[t(o.icon,{className:o.color,size:20}),i("div",{className:"space-y-1",children:[t("h3",{className:"font-semibold",children:o.name}),t("p",{className:"text-muted-foreground text-xs",children:o.description}),t("code",{className:"text-violet-400 text-xs",children:o.factory})]})]},o.name))})]}),i("div",{className:"space-y-6",children:[i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"1) Operations (Commands & Queries)"}),t("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."}),t(Q,{language:"typescript",filename:"src/contracts/user.operation.ts",code:`import { defineCommand, defineQuery } from "@contractspec/lib.contracts-spec";
+open https://www.contractspec.io/sandbox?template=form-showcase`;import{CodeBlock as Q}from"@contractspec/lib.design-system";import{HStack as Ve,VStack as M}from"@contractspec/lib.design-system/layout";import{List as He,ListItem as ce}from"@contractspec/lib.design-system/list";import{Code as be,H1 as xe,H2 as H,H3 as Ne,P as _,Text as J}from"@contractspec/lib.design-system/typography";import x from"@contractspec/lib.ui-link";import{ChevronRight as je}from"lucide-react";import{jsx as l,jsxs as k}from"react/jsx-runtime";function et(){return k(M,{className:"space-y-8",children:[k(M,{className:"space-y-3",children:[l(xe,{className:"font-bold text-4xl",children:"Build a contract-driven form"}),l(_,{className:"text-lg text-muted-foreground",children:"Define form data, fields, layout, policy, and submit behavior once, then let your app render from the same ContractSpec surface."})]}),k(M,{className:"card-subtle space-y-4 p-6",children:[l(H,{className:"font-bold text-2xl",children:"What you'll build"}),k(He,{className:"space-y-2 text-muted-foreground text-sm",children:[l(ce,{children:l(J,{children:"A schema-backed FormSpec for a lead capture form."})}),l(ce,{children:l(J,{children:"A FormRegistry that exposes the latest version by stable key."})}),l(ce,{children:l(J,{children:"A React renderer that keeps UI, validation, and policy aligned."})})]})]}),k(M,{className:"space-y-6",children:[k(M,{className:"space-y-3",children:[l(H,{className:"font-bold text-2xl",children:"1) Define the form spec"}),k(_,{className:"text-muted-foreground text-sm",children:["Create ",l(be,{children:"src/contracts/forms/lead-capture.form.ts"}),":"]}),l(Q,{language:"typescript",filename:"src/contracts/forms/lead-capture.form.ts",code:ge})]}),k(M,{className:"card-subtle space-y-3 p-6",children:[l(Ne,{className:"font-semibold text-lg",children:"Need every form field?"}),k(_,{className:"text-muted-foreground text-sm",children:["Start from the"," ",l(x,{href:"/docs/examples/form-showcase",children:"Form Showcase example"})," ","or the"," ",l(x,{href:"/templates?tag=forms",children:"form template catalog"}),". It is focused only on forms and covers field kinds, section layouts, step layouts, arrays, groups, conditionals, and validation hints."]}),l(Q,{language:"bash",filename:"form-showcase-template",code:ve})]}),k(M,{className:"space-y-3",children:[l(H,{className:"font-bold text-2xl",children:"2) Render from the contract"}),l(_,{className:"text-muted-foreground text-sm",children:"Use the shared renderer, or provide your own driver if your app uses a different component library."}),l(Q,{language:"tsx",filename:"src/components/LeadCapturePanel.tsx",code:ye})]}),k(M,{className:"space-y-3",children:[l(H,{className:"font-bold text-2xl",children:"3) Validate and evolve"}),l(Q,{language:"bash",filename:"validate-form",code:"contractspec validate src/contracts/forms/lead-capture.form.ts"}),k(_,{className:"text-muted-foreground text-sm",children:["Expected output: ",l(be,{children:"Validation passed"}),". When the form becomes public contract surface, version changes deliberately instead of editing field meaning in place."]})]}),k(M,{className:"card-subtle space-y-3 p-6",children:[l(Ne,{className:"font-semibold text-lg",children:"Repo tutorial"}),l(_,{className:"text-muted-foreground text-sm",children:"The repository guide adds the longer implementation checklist, custom renderer notes, and rollout rules."}),l(Q,{language:"bash",filename:"repo-guide",code:"open docs/tutorials/contract-driven-forms.md"})]}),l(N,{title:"Need governed form changes?",body:"Studio can connect form edits to customer evidence, approval packets, and rollout checks before teams regenerate public surfaces."})]}),k(Ve,{className:"flex items-center gap-4 pt-4",children:[k(x,{href:"/docs/guides/generate-docs-clients-schemas",className:"btn-primary",children:[l(J,{children:"Next: Generate docs + clients"}),l(je,{size:16})]}),l(x,{href:"/docs/guides",className:"btn-ghost",children:l(J,{children:"Back to guides"})})]})]})}import{CodeBlock as Y}from"@contractspec/lib.design-system";import we from"@contractspec/lib.ui-link";import{ChevronRight as tt,Globe as at,Layers as ot,Shield as rt,Zap as nt}from"lucide-react";import{jsx as t,jsxs as i}from"react/jsx-runtime";var ct=[{name:"Operations",factory:"defineCommand / defineQuery",description:"API endpoints with input/output schemas, validation, and policy.",icon:nt,color:"text-blue-400"},{name:"Events",factory:"defineEvent",description:"Domain events with typed payloads and PII handling.",icon:ot,color:"text-green-400"},{name:"Capabilities",factory:"defineCapability",description:"Feature groupings that link operations, events, and UIs.",icon:rt,color:"text-purple-400"},{name:"Presentations",factory:"definePresentation",description:"UI specifications for rendering data and handling interactions.",icon:at,color:"text-orange-400"}];function it(){return i("div",{className:"space-y-8",children:[i("div",{className:"space-y-3",children:[t("h1",{className:"font-bold text-4xl",children:"Contract Types Overview"}),t("p",{className:"text-lg text-muted-foreground",children:"Learn about the different contract types in ContractSpec and when to use each one when you are making the system boundary explicit."})]}),i("div",{className:"card-subtle space-y-4 p-6",children:[t("h2",{className:"font-bold text-2xl",children:"Core Contract Types"}),t("div",{className:"grid gap-3 md:grid-cols-2",children:ct.map((o)=>i("div",{className:"flex items-start gap-3 rounded-lg border border-white/10 p-4",children:[t(o.icon,{className:o.color,size:20}),i("div",{className:"space-y-1",children:[t("h3",{className:"font-semibold",children:o.name}),t("p",{className:"text-muted-foreground text-xs",children:o.description}),t("code",{className:"text-violet-400 text-xs",children:o.factory})]})]},o.name))})]}),i("div",{className:"space-y-6",children:[i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"1) Operations (Commands & Queries)"}),t("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."}),t(Y,{language:"typescript",filename:"src/contracts/user.operation.ts",code:`import { defineCommand, defineQuery } from "@contractspec/lib.contracts-spec";
 import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
 
 // Command: Mutates state (creates a user)
@@ -226,7 +226,7 @@ export const GetUserQuery = defineQuery({
     }),
   },
   policy: { auth: "user" },
-});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"2) Events"}),t("p",{className:"text-muted-foreground text-sm",children:"Events represent domain occurrences. They have typed payloads with PII field marking for compliance."}),t(Q,{language:"typescript",filename:"src/contracts/user.event.ts",code:`import { defineEvent } from "@contractspec/lib.contracts-spec";
+});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"2) Events"}),t("p",{className:"text-muted-foreground text-sm",children:"Events represent domain occurrences. They have typed payloads with PII field marking for compliance."}),t(Y,{language:"typescript",filename:"src/contracts/user.event.ts",code:`import { defineEvent } from "@contractspec/lib.contracts-spec";
 import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
 
 export const UserCreatedEvent = defineEvent({
@@ -267,7 +267,7 @@ export const UserDeletedEvent = defineEvent({
       reason: { type: ScalarTypeEnum.String(), isOptional: true },
     },
   }),
-});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"3) Capabilities"}),t("p",{className:"text-muted-foreground text-sm",children:"Capabilities group related operations, events, and presentations. They define feature boundaries and dependencies."}),t(Q,{language:"typescript",filename:"src/contracts/user-management.capability.ts",code:`import { defineCapability } from "@contractspec/lib.contracts-spec";
+});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"3) Capabilities"}),t("p",{className:"text-muted-foreground text-sm",children:"Capabilities group related operations, events, and presentations. They define feature boundaries and dependencies."}),t(Y,{language:"typescript",filename:"src/contracts/user-management.capability.ts",code:`import { defineCapability } from "@contractspec/lib.contracts-spec";
 
 export const UserManagementCapability = defineCapability({
   meta: {
@@ -310,7 +310,7 @@ export const AdminUserCapability = defineCapability({
     { surface: "operation", key: "user.ban", version: "1.0.0" },
     { surface: "operation", key: "user.impersonate", version: "1.0.0" },
   ],
-});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"4) Presentations"}),t("p",{className:"text-muted-foreground text-sm",children:"Presentations define UI specifications. They link to capabilities and specify how data should be displayed."}),t(Q,{language:"typescript",filename:"src/contracts/user-list.presentation.ts",code:`import { definePresentation } from "@contractspec/lib.contracts-spec";
+});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"4) Presentations"}),t("p",{className:"text-muted-foreground text-sm",children:"Presentations define UI specifications. They link to capabilities and specify how data should be displayed."}),t(Y,{language:"typescript",filename:"src/contracts/user-list.presentation.ts",code:`import { definePresentation } from "@contractspec/lib.contracts-spec";
 
 export const UserListPresentation = definePresentation({
   meta: {
@@ -332,7 +332,7 @@ export const UserListPresentation = definePresentation({
     pagination: { defaultPageSize: 25 },
     search: { fields: ["name", "email"] },
   },
-});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"5) Additional Contract Types"}),t("p",{className:"text-muted-foreground text-sm",children:"ContractSpec provides specialized contracts for different concerns:"}),i("div",{className:"grid gap-4 md:grid-cols-2",children:[i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Policy"}),t("code",{className:"text-violet-400 text-xs",children:"definePolicy"}),t("p",{className:"text-muted-foreground text-xs",children:"RBAC/ABAC rules, rate limits, and access control."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Workflow"}),t("code",{className:"text-violet-400 text-xs",children:"defineWorkflow"}),t("p",{className:"text-muted-foreground text-xs",children:"Multi-step processes with states, transitions, and SLAs."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Translation"}),t("code",{className:"text-violet-400 text-xs",children:"defineTranslation"}),t("p",{className:"text-muted-foreground text-xs",children:"i18n messages with ICU format and locale fallbacks."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Integration"}),t("code",{className:"text-violet-400 text-xs",children:"defineIntegration"}),t("p",{className:"text-muted-foreground text-xs",children:"External service connections and API adapters."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Form"}),t("code",{className:"text-violet-400 text-xs",children:"defineFormSpec"}),t("p",{className:"text-muted-foreground text-xs",children:"Form definitions with fields, validation, and layouts."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Data View"}),t("code",{className:"text-violet-400 text-xs",children:"defineDataView"}),t("p",{className:"text-muted-foreground text-xs",children:"Read-only data projections and aggregations."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Feature"}),t("code",{className:"text-violet-400 text-xs",children:"defineFeature"}),t("p",{className:"text-muted-foreground text-xs",children:"Feature flags and progressive rollout configurations."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Test"}),t("code",{className:"text-violet-400 text-xs",children:"defineTestSpec"}),t("p",{className:"text-muted-foreground text-xs",children:"Contract-driven test scenarios and fixtures."})]})]})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"6) Registering Contracts"}),t("p",{className:"text-muted-foreground text-sm",children:"Each contract type has a registry for lookup and validation."}),t(Q,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
+});`})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"5) Additional Contract Types"}),t("p",{className:"text-muted-foreground text-sm",children:"ContractSpec provides specialized contracts for different concerns:"}),i("div",{className:"grid gap-4 md:grid-cols-2",children:[i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Policy"}),t("code",{className:"text-violet-400 text-xs",children:"definePolicy"}),t("p",{className:"text-muted-foreground text-xs",children:"RBAC/ABAC rules, rate limits, and access control."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Workflow"}),t("code",{className:"text-violet-400 text-xs",children:"defineWorkflow"}),t("p",{className:"text-muted-foreground text-xs",children:"Multi-step processes with states, transitions, and SLAs."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Translation"}),t("code",{className:"text-violet-400 text-xs",children:"defineTranslation"}),t("p",{className:"text-muted-foreground text-xs",children:"i18n messages with ICU format and locale fallbacks."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Integration"}),t("code",{className:"text-violet-400 text-xs",children:"defineIntegration"}),t("p",{className:"text-muted-foreground text-xs",children:"External service connections and API adapters."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Form"}),t("code",{className:"text-violet-400 text-xs",children:"defineFormSpec"}),t("p",{className:"text-muted-foreground text-xs",children:"Form definitions with fields, validation, and layouts."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Data View"}),t("code",{className:"text-violet-400 text-xs",children:"defineDataView"}),t("p",{className:"text-muted-foreground text-xs",children:"Read-only data projections and aggregations."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Feature"}),t("code",{className:"text-violet-400 text-xs",children:"defineFeature"}),t("p",{className:"text-muted-foreground text-xs",children:"Feature flags and progressive rollout configurations."})]}),i("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold",children:"Test"}),t("code",{className:"text-violet-400 text-xs",children:"defineTestSpec"}),t("p",{className:"text-muted-foreground text-xs",children:"Contract-driven test scenarios and fixtures."})]})]})]}),i("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"6) Registering Contracts"}),t("p",{className:"text-muted-foreground text-sm",children:"Each contract type has a registry for lookup and validation."}),t(Y,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
   OperationSpecRegistry,
   installOp,
 } from "@contractspec/lib.contracts-spec/operations";
@@ -362,7 +362,7 @@ installOp(operationRegistry, GetUserQuery, async (input) => {
 
 // Register events and capabilities
 eventRegistry.register(UserCreatedEvent);
-capabilityRegistry.register(UserManagementCapability);`})]}),i("div",{className:"card-subtle space-y-3 p-6",children:[t("h3",{className:"font-semibold text-lg",children:"Contract Type Decision Guide"}),i("table",{className:"w-full text-sm",children:[t("thead",{children:i("tr",{className:"border-white/10 border-b",children:[t("th",{className:"py-2 text-left",children:"When you need..."}),t("th",{className:"py-2 text-left",children:"Use this contract"})]})}),i("tbody",{className:"text-muted-foreground",children:[i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"An API endpoint that changes data"}),t("td",{className:"py-2",children:t("code",{children:"defineCommand"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"An API endpoint that reads data"}),t("td",{className:"py-2",children:t("code",{children:"defineQuery"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Async notification of something that happened"}),t("td",{className:"py-2",children:t("code",{children:"defineEvent"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Group related specs under a feature"}),t("td",{className:"py-2",children:t("code",{children:"defineCapability"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Define UI rendering specifications"}),t("td",{className:"py-2",children:t("code",{children:"definePresentation"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Access control and rate limiting"}),t("td",{className:"py-2",children:t("code",{children:"definePolicy"})})]}),i("tr",{children:[t("td",{className:"py-2",children:"Multi-step business processes"}),t("td",{className:"py-2",children:t("code",{children:"defineWorkflow"})})]})]})]})]}),t(v,{title:"Need to decide which contract should change next?",body:"Studio uses evidence and focus constraints to generate decision briefs, patch intents, and execution-ready task packs."})]}),i("div",{className:"flex items-center gap-4 pt-4",children:[i(be,{href:"/docs/guides/nextjs-one-endpoint",className:"btn-primary",children:["Next: Add your first endpoint ",t(Ve,{size:16})]}),t(be,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}var ve=`import {
+capabilityRegistry.register(UserManagementCapability);`})]}),i("div",{className:"card-subtle space-y-3 p-6",children:[t("h3",{className:"font-semibold text-lg",children:"Contract Type Decision Guide"}),i("table",{className:"w-full text-sm",children:[t("thead",{children:i("tr",{className:"border-white/10 border-b",children:[t("th",{className:"py-2 text-left",children:"When you need..."}),t("th",{className:"py-2 text-left",children:"Use this contract"})]})}),i("tbody",{className:"text-muted-foreground",children:[i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"An API endpoint that changes data"}),t("td",{className:"py-2",children:t("code",{children:"defineCommand"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"An API endpoint that reads data"}),t("td",{className:"py-2",children:t("code",{children:"defineQuery"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Async notification of something that happened"}),t("td",{className:"py-2",children:t("code",{children:"defineEvent"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Group related specs under a feature"}),t("td",{className:"py-2",children:t("code",{children:"defineCapability"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Define UI rendering specifications"}),t("td",{className:"py-2",children:t("code",{children:"definePresentation"})})]}),i("tr",{className:"border-white/5 border-b",children:[t("td",{className:"py-2",children:"Access control and rate limiting"}),t("td",{className:"py-2",children:t("code",{children:"definePolicy"})})]}),i("tr",{children:[t("td",{className:"py-2",children:"Multi-step business processes"}),t("td",{className:"py-2",children:t("code",{children:"defineWorkflow"})})]})]})]})]}),t(N,{title:"Need to decide which contract should change next?",body:"Studio uses evidence and focus constraints to generate decision briefs, patch intents, and execution-ready task packs."})]}),i("div",{className:"flex items-center gap-4 pt-4",children:[i(we,{href:"/docs/guides/nextjs-one-endpoint",className:"btn-primary",children:["Next: Add your first endpoint ",t(tt,{size:16})]}),t(we,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}var ke=`import {
   createImportPlan,
   createRecordBatch,
   defineDataExchangeTemplate,
@@ -446,7 +446,7 @@ const preview = previewImport(
 );
 
 console.log(preview.plan.mappingSource); // "template"
-console.log(preview.normalizedRecords[0]);`,Ne=`import { defineDataExchangeTemplate } from "@contractspec/lib.data-exchange-core";
+console.log(preview.normalizedRecords[0]);`,Ce=`import { defineDataExchangeTemplate } from "@contractspec/lib.data-exchange-core";
 import { dryRunImport, executeImport } from "@contractspec/lib.data-exchange-server";
 
 const template = defineDataExchangeTemplate({
@@ -489,7 +489,7 @@ if (blockingIssues.length === 0) {
     template,
     formatProfile,
   });
-}`,we=`"use client";
+}`,Se=`"use client";
 
 import { useDataExchangeController } from "@contractspec/lib.data-exchange-client";
 
@@ -519,14 +519,14 @@ export function ImportMappingReview({ preview }) {
       ) : null}
     </section>
   );
-}`,ke=`You are adding an import flow to a ContractSpec app.
+}`,Ie=`You are adding an import flow to a ContractSpec app.
 
 Define a reusable data-exchange template for this canonical schema:
 - target fields, required flags, and display labels
 - known partner column aliases
 - value formats for numbers, dates, booleans, JSON, split/join lists, currency, and percentages
 
-Wire the template into core preview planning and server dry-run execution. Keep explicit mappings higher precedence than template resolution. Return the template, preview call, server dry-run call, and tests for alias matching plus localized formatting.`,Ce=`A partner sent a CSV/JSON/XML file that does not match our recommended import template.
+Wire the template into core preview planning and server dry-run execution. Keep explicit mappings higher precedence than template resolution. Return the template, preview call, server dry-run call, and tests for alias matching plus localized formatting.`,Ee=`A partner sent a CSV/JSON/XML file that does not match our recommended import template.
 
 Compare the incoming headers and value samples against this ContractSpec data-exchange template. Propose:
 - source-to-target column matches with confidence
@@ -534,11 +534,11 @@ Compare the incoming headers and value samples against this ContractSpec data-ex
 - ignored source columns
 - format overrides for localized numbers, booleans, dates, JSON, split/join lists, currency, or percentages
 
-Do not execute the import. Produce a dry-run plan and the user-facing review copy.`,Se=`cd packages/libs/data-exchange-core && bun test && bun run typecheck && bun run lint:check
+Do not execute the import. Produce a dry-run plan and the user-facing review copy.`,Ae=`cd packages/libs/data-exchange-core && bun test && bun run typecheck && bun run lint:check
 cd packages/libs/data-exchange-client && bun test && bun run typecheck && bun run lint:check
-cd packages/libs/data-exchange-server && bun test && bun run typecheck && bun run lint:check`;import{CodeBlock as F}from"@contractspec/lib.design-system";import{HStack as rt,VStack as E}from"@contractspec/lib.design-system/layout";import{List as re,ListItem as J}from"@contractspec/lib.design-system/list";import{Code as ne,H1 as nt,H2 as Y,H3 as V,P as x,Text as D}from"@contractspec/lib.design-system/typography";import Ie from"@contractspec/lib.ui-link";import{ChevronRight as ct}from"lucide-react";import{jsx as r,jsxs as y}from"react/jsx-runtime";var it=["Explicit mappings win first, so existing integrations can keep their current mapping arrays.","Template resolution checks exact headers, aliases, normalized labels, and SchemaModel fallback inference.","Format profiles can override formats by target field or template column key without changing the template.","Required template columns become visible preview issues when no source column can be matched."],lt=["text trim and case normalization","localized numbers with decimal and thousands separators","custom true/false boolean labels","dates and datetimes with accepted input formats","JSON parsing, empty-as-null, and default values","split/join delimiters, currency symbols, and percentages"];function st(){return y(E,{className:"space-y-8",children:[y(E,{className:"space-y-3",children:[r(D,{className:"editorial-kicker",children:"Build"}),r(nt,{className:"font-bold text-4xl",children:"Import flexible files with data-exchange templates"}),r(x,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"Publish one recommended import shape, then let users import CSV/JSON/XML files with partner-specific headers, skipped rows, localized values, and alternate metadata layouts."})]}),y(E,{className:"card-subtle space-y-4 p-6",children:[r(Y,{className:"font-bold text-2xl",children:"What you'll build"}),y(re,{className:"space-y-2 text-muted-foreground text-sm",children:[r(J,{children:r(D,{children:"A canonical template with target fields, aliases, and formats."})}),r(J,{children:r(D,{children:"A dry-run import that reports confidence, gaps, and ignored columns."})}),r(J,{children:r(D,{children:"A client review state where users remap, update formats, or accept inferred mappings."})})]})]}),y(E,{className:"space-y-4",children:[r(Y,{className:"font-bold text-2xl",children:"1) Define the template"}),y(x,{className:"text-muted-foreground text-sm leading-7",children:["Use ",r(ne,{children:"defineDataExchangeTemplate"})," for neutral import/export naming. ",r(ne,{children:"defineImportTemplate"})," and"," ",r(ne,{children:"defineExportTemplate"})," remain available aliases."]}),r(F,{language:"typescript",filename:"src/data-exchange/accounts-import.ts",code:ve})]}),y(E,{className:"grid gap-4 md:grid-cols-2",children:[y(E,{className:"card-subtle space-y-3 p-6",children:[r(V,{className:"font-bold text-xl",children:"Mapping precedence"}),r(re,{className:"space-y-2 text-muted-foreground text-sm",children:it.map((o)=>r(J,{children:r(D,{children:o})},o))})]}),y(E,{className:"card-subtle space-y-3 p-6",children:[r(V,{className:"font-bold text-xl",children:"Supported value formats"}),r(re,{className:"space-y-2 text-muted-foreground text-sm",children:lt.map((o)=>r(J,{children:r(D,{children:o})},o))})]})]}),y(E,{className:"space-y-4",children:[r(Y,{className:"font-bold text-2xl",children:"2) Dry-run partner CSV, JSON, or XML files on the server"}),r(x,{className:"text-muted-foreground text-sm leading-7",children:"File, HTTP, and storage adapters accept codec options. CSV can set delimiters, quotes, skipped rows, header rows, or explicit columns. JSON can read records and metadata from custom keys. XML can use custom root, record, metadata, and attribute fields."}),r(F,{language:"typescript",filename:"src/server/import-accounts.ts",code:Ne})]}),y(E,{className:"space-y-4",children:[r(Y,{className:"font-bold text-2xl",children:"3) Let users review the mapping"}),r(x,{className:"text-muted-foreground text-sm leading-7",children:"The shared controller exposes template rows, matched source columns, confidence, required status, formatting summaries, unmatched required rows, and ignored source columns. Actions let users remap columns, select aliases, update field formats, reset to the template, or accept inferred mappings."}),r(F,{language:"tsx",filename:"src/components/ImportMappingReview.tsx",code:we})]}),y(E,{className:"space-y-4",children:[r(Y,{className:"font-bold text-2xl",children:"4) Verify the package stack"}),r(F,{language:"bash",filename:"verification",code:Se})]}),y(E,{className:"grid gap-4 md:grid-cols-2",children:[y(E,{className:"card-subtle space-y-3 p-6",children:[r(V,{className:"font-bold text-xl",children:"Prompt: build a template"}),r(F,{language:"markdown",filename:"template-authoring.prompt.md",code:ke})]}),y(E,{className:"card-subtle space-y-3 p-6",children:[r(V,{className:"font-bold text-xl",children:"Prompt: inspect a partner file"}),r(F,{language:"markdown",filename:"partner-import-review.prompt.md",code:Ce})]})]}),y(rt,{className:"flex flex-wrap items-center gap-4 pt-4",children:[y(Ie,{href:"/llms/lib.data-exchange-core",className:"btn-primary",children:[r(D,{children:"Core package guide"}),r(ct,{size:16})]}),r(Ie,{href:"/llms/lib.data-exchange-server",className:"btn-ghost",children:r(D,{children:"Server package guide"})})]})]})}import{CodeBlock as ce}from"@contractspec/lib.design-system";import Ee from"@contractspec/lib.ui-link";import{ChevronRight as dt}from"lucide-react";import{jsx as h,jsxs as k}from"react/jsx-runtime";function pt(){return k("div",{className:"space-y-8",children:[k("div",{className:"space-y-3",children:[h("h1",{className:"font-bold text-4xl",children:"Build the docs pipeline"}),h("p",{className:"text-lg text-muted-foreground",children:"Generate reference docs, chunk the index, and wire the docs pages the same way this repo does."})]}),k("div",{className:"card-subtle space-y-4 p-6",children:[h("h2",{className:"font-bold text-2xl",children:"What you'll build"}),k("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[h("li",{children:"Generated Markdown and a chunked index manifest."}),h("li",{children:"Reference routes powered by the docs loader."}),h("li",{children:"Versioned outputs you can publish per release."})]})]}),k("div",{className:"space-y-6",children:[k("div",{className:"space-y-3",children:[h("h2",{className:"font-bold text-2xl",children:"1) Generate contract docs"}),h(ce,{language:"bash",filename:"generate-contract-docs",code:"contractspec generate"}),k("p",{className:"text-muted-foreground text-sm",children:["Expected output: Markdown in ",h("code",{children:"generated/docs"}),"."]})]}),k("div",{className:"space-y-3",children:[h("h2",{className:"font-bold text-2xl",children:"2) Build the docs index"}),h(ce,{language:"bash",filename:"docs-generate",code:`bun docs:generate
+cd packages/libs/data-exchange-server && bun test && bun run typecheck && bun run lint:check`;import{CodeBlock as q}from"@contractspec/lib.design-system";import{HStack as lt,VStack as A}from"@contractspec/lib.design-system/layout";import{List as ie,ListItem as $}from"@contractspec/lib.design-system/list";import{Code as le,H1 as st,H2 as X,H3 as j,P as ee,Text as U}from"@contractspec/lib.design-system/typography";import Pe from"@contractspec/lib.ui-link";import{ChevronRight as dt}from"lucide-react";import{jsx as r,jsxs as v}from"react/jsx-runtime";var pt=["Explicit mappings win first, so existing integrations can keep their current mapping arrays.","Template resolution checks exact headers, aliases, normalized labels, and SchemaModel fallback inference.","Format profiles can override formats by target field or template column key without changing the template.","Required template columns become visible preview issues when no source column can be matched."],mt=["text trim and case normalization","localized numbers with decimal and thousands separators","custom true/false boolean labels","dates and datetimes with accepted input formats","JSON parsing, empty-as-null, and default values","split/join delimiters, currency symbols, and percentages"];function ut(){return v(A,{className:"space-y-8",children:[v(A,{className:"space-y-3",children:[r(U,{className:"editorial-kicker",children:"Build"}),r(st,{className:"font-bold text-4xl",children:"Import flexible files with data-exchange templates"}),r(ee,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"Publish one recommended import shape, then let users import CSV/JSON/XML files with partner-specific headers, skipped rows, localized values, and alternate metadata layouts."})]}),v(A,{className:"card-subtle space-y-4 p-6",children:[r(X,{className:"font-bold text-2xl",children:"What you'll build"}),v(ie,{className:"space-y-2 text-muted-foreground text-sm",children:[r($,{children:r(U,{children:"A canonical template with target fields, aliases, and formats."})}),r($,{children:r(U,{children:"A dry-run import that reports confidence, gaps, and ignored columns."})}),r($,{children:r(U,{children:"A client review state where users remap, update formats, or accept inferred mappings."})})]})]}),v(A,{className:"space-y-4",children:[r(X,{className:"font-bold text-2xl",children:"1) Define the template"}),v(ee,{className:"text-muted-foreground text-sm leading-7",children:["Use ",r(le,{children:"defineDataExchangeTemplate"})," for neutral import/export naming. ",r(le,{children:"defineImportTemplate"})," and"," ",r(le,{children:"defineExportTemplate"})," remain available aliases."]}),r(q,{language:"typescript",filename:"src/data-exchange/accounts-import.ts",code:ke})]}),v(A,{className:"grid gap-4 md:grid-cols-2",children:[v(A,{className:"card-subtle space-y-3 p-6",children:[r(j,{className:"font-bold text-xl",children:"Mapping precedence"}),r(ie,{className:"space-y-2 text-muted-foreground text-sm",children:pt.map((o)=>r($,{children:r(U,{children:o})},o))})]}),v(A,{className:"card-subtle space-y-3 p-6",children:[r(j,{className:"font-bold text-xl",children:"Supported value formats"}),r(ie,{className:"space-y-2 text-muted-foreground text-sm",children:mt.map((o)=>r($,{children:r(U,{children:o})},o))})]})]}),v(A,{className:"space-y-4",children:[r(X,{className:"font-bold text-2xl",children:"2) Dry-run partner CSV, JSON, or XML files on the server"}),r(ee,{className:"text-muted-foreground text-sm leading-7",children:"File, HTTP, and storage adapters accept codec options. CSV can set delimiters, quotes, skipped rows, header rows, or explicit columns. JSON can read records and metadata from custom keys. XML can use custom root, record, metadata, and attribute fields."}),r(q,{language:"typescript",filename:"src/server/import-accounts.ts",code:Ce})]}),v(A,{className:"space-y-4",children:[r(X,{className:"font-bold text-2xl",children:"3) Let users review the mapping"}),r(ee,{className:"text-muted-foreground text-sm leading-7",children:"The shared controller exposes template rows, matched source columns, confidence, required status, formatting summaries, unmatched required rows, and ignored source columns. Actions let users remap columns, select aliases, update field formats, reset to the template, or accept inferred mappings."}),r(q,{language:"tsx",filename:"src/components/ImportMappingReview.tsx",code:Se})]}),v(A,{className:"space-y-4",children:[r(X,{className:"font-bold text-2xl",children:"4) Verify the package stack"}),r(q,{language:"bash",filename:"verification",code:Ae})]}),v(A,{className:"grid gap-4 md:grid-cols-2",children:[v(A,{className:"card-subtle space-y-3 p-6",children:[r(j,{className:"font-bold text-xl",children:"Prompt: build a template"}),r(q,{language:"markdown",filename:"template-authoring.prompt.md",code:Ie})]}),v(A,{className:"card-subtle space-y-3 p-6",children:[r(j,{className:"font-bold text-xl",children:"Prompt: inspect a partner file"}),r(q,{language:"markdown",filename:"partner-import-review.prompt.md",code:Ee})]})]}),v(lt,{className:"flex flex-wrap items-center gap-4 pt-4",children:[v(Pe,{href:"/llms/lib.data-exchange-core",className:"btn-primary",children:[r(U,{children:"Core package guide"}),r(dt,{size:16})]}),r(Pe,{href:"/llms/lib.data-exchange-server",className:"btn-ghost",children:r(U,{children:"Server package guide"})})]})]})}import{CodeBlock as se}from"@contractspec/lib.design-system";import Re from"@contractspec/lib.ui-link";import{ChevronRight as ht}from"lucide-react";import{jsx as f,jsxs as C}from"react/jsx-runtime";function ft(){return C("div",{className:"space-y-8",children:[C("div",{className:"space-y-3",children:[f("h1",{className:"font-bold text-4xl",children:"Build the docs pipeline"}),f("p",{className:"text-lg text-muted-foreground",children:"Generate reference docs, chunk the index, and wire the docs pages the same way this repo does."})]}),C("div",{className:"card-subtle space-y-4 p-6",children:[f("h2",{className:"font-bold text-2xl",children:"What you'll build"}),C("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[f("li",{children:"Generated Markdown and a chunked index manifest."}),f("li",{children:"Reference routes powered by the docs loader."}),f("li",{children:"Versioned outputs you can publish per release."})]})]}),C("div",{className:"space-y-6",children:[C("div",{className:"space-y-3",children:[f("h2",{className:"font-bold text-2xl",children:"1) Generate contract docs"}),f(se,{language:"bash",filename:"generate-contract-docs",code:"contractspec generate"}),C("p",{className:"text-muted-foreground text-sm",children:["Expected output: Markdown in ",f("code",{children:"generated/docs"}),"."]})]}),C("div",{className:"space-y-3",children:[f("h2",{className:"font-bold text-2xl",children:"2) Build the docs index"}),f(se,{language:"bash",filename:"docs-generate",code:`bun docs:generate
 # versioned output
-bun docs:generate -- --version v1.0.0`}),k("p",{className:"text-muted-foreground text-sm",children:["This writes ",h("code",{children:"docs-index.manifest.json"})," and chunked",h("code",{children:"docs-index.*.json"})," files in the generated docs bundle."]})]}),k("div",{className:"space-y-3",children:[h("h2",{className:"font-bold text-2xl",children:"3) Wire reference routes"}),h(ce,{language:"tsx",filename:"docs-reference-route",code:`import { notFound } from "next/navigation";
+bun docs:generate -- --version v1.0.0`}),C("p",{className:"text-muted-foreground text-sm",children:["This writes ",f("code",{children:"docs-index.manifest.json"})," and chunked",f("code",{children:"docs-index.*.json"})," files in the generated docs bundle."]})]}),C("div",{className:"space-y-3",children:[f("h2",{className:"font-bold text-2xl",children:"3) Wire reference routes"}),f(se,{language:"tsx",filename:"docs-reference-route",code:`import { notFound } from "next/navigation";
 import {
   DocsReferenceIndexPage,
   DocsReferencePage,
@@ -556,7 +556,7 @@ export default async function Page({ params }: { params: { slug?: string[] } })
   const doc = await getGeneratedDocById(slug);
   if (!doc) notFound();
   return <DocsReferencePage entry={doc.entry} content={doc.content} />;
-}`}),k("p",{className:"text-muted-foreground text-sm",children:["Use the index page on ",h("code",{children:"/docs/reference"})," to render the searchable list."]})]}),k("div",{className:"card-subtle space-y-3 p-6",children:[h("h3",{className:"font-semibold text-lg",children:"Repo reference"}),k("p",{className:"text-muted-foreground text-sm",children:["This repo wires docs under"," ",h("code",{children:"packages/apps/web-landing/src/app/docs/reference"}),"."]})]}),h(v,{title:"Need decision-to-export automation?",body:"Studio exports evidence-backed spec changes and task packs to Linear, Jira, Notion, and GitHub."})]}),k("div",{className:"flex items-center gap-4 pt-4",children:[k(Ee,{href:"/docs/guides/ci-contract-diff-gating",className:"btn-primary",children:["Next: CI gating ",h(dt,{size:16})]}),h(Ee,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as ie}from"@contractspec/lib.design-system";import Pe from"@contractspec/lib.ui-link";import{ChevronRight as mt}from"lucide-react";import{jsx as d,jsxs as R}from"react/jsx-runtime";function ut(){return R("div",{className:"space-y-8",children:[R("div",{className:"space-y-3",children:[d("h1",{className:"font-bold text-4xl",children:"Build a first module bundle"}),d("p",{className:"text-lg text-muted-foreground",children:"Define one bundle spec, resolve it for a real route and preference profile, then render the resulting surface plan through the React host layer."})]}),R("div",{className:"card-subtle space-y-4 p-6",children:[d("h2",{className:"font-bold text-2xl",children:"What you'll build"}),R("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[d("li",{children:"One `ModuleBundleSpec` with a route and workbench surface."}),d("li",{children:"One `ResolvedSurfacePlan` from `resolveBundle`."}),d("li",{children:"One React host using `BundleProvider` and `BundleRenderer`."})]})]}),R("div",{className:"space-y-6",children:[R("div",{className:"space-y-3",children:[d("h2",{className:"font-bold text-2xl",children:"1) Define the bundle spec"}),d("p",{className:"text-muted-foreground text-sm",children:"The bundle spec is the durable contract. It owns route selection, surface shape, layouts, data recipes, and verification coverage for all seven preference dimensions."}),d(ie,{language:"typescript",filename:"src/bundles/support.workbench.bundle.ts",code:`import { defineModuleBundle } from "@contractspec/lib.surface-runtime/spec/define-module-bundle";
+}`}),C("p",{className:"text-muted-foreground text-sm",children:["Use the index page on ",f("code",{children:"/docs/reference"})," to render the searchable list."]})]}),C("div",{className:"card-subtle space-y-3 p-6",children:[f("h3",{className:"font-semibold text-lg",children:"Repo reference"}),C("p",{className:"text-muted-foreground text-sm",children:["This repo wires docs under"," ",f("code",{children:"packages/apps/web-landing/src/app/docs/reference"}),"."]})]}),f(N,{title:"Need decision-to-export automation?",body:"Studio exports evidence-backed spec changes and task packs to Linear, Jira, Notion, and GitHub."})]}),C("div",{className:"flex items-center gap-4 pt-4",children:[C(Re,{href:"/docs/guides/ci-contract-diff-gating",className:"btn-primary",children:["Next: CI gating ",f(ht,{size:16})]}),f(Re,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as de}from"@contractspec/lib.design-system";import Oe from"@contractspec/lib.ui-link";import{ChevronRight as gt}from"lucide-react";import{jsx as d,jsxs as O}from"react/jsx-runtime";function yt(){return O("div",{className:"space-y-8",children:[O("div",{className:"space-y-3",children:[d("h1",{className:"font-bold text-4xl",children:"Build a first module bundle"}),d("p",{className:"text-lg text-muted-foreground",children:"Define one bundle spec, resolve it for a real route and preference profile, then render the resulting surface plan through the React host layer."})]}),O("div",{className:"card-subtle space-y-4 p-6",children:[d("h2",{className:"font-bold text-2xl",children:"What you'll build"}),O("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[d("li",{children:"One `ModuleBundleSpec` with a route and workbench surface."}),d("li",{children:"One `ResolvedSurfacePlan` from `resolveBundle`."}),d("li",{children:"One React host using `BundleProvider` and `BundleRenderer`."})]})]}),O("div",{className:"space-y-6",children:[O("div",{className:"space-y-3",children:[d("h2",{className:"font-bold text-2xl",children:"1) Define the bundle spec"}),d("p",{className:"text-muted-foreground text-sm",children:"The bundle spec is the durable contract. It owns route selection, surface shape, layouts, data recipes, and verification coverage for all seven preference dimensions."}),d(de,{language:"typescript",filename:"src/bundles/support.workbench.bundle.ts",code:`import { defineModuleBundle } from "@contractspec/lib.surface-runtime/spec/define-module-bundle";
 
 export const SupportWorkbenchBundle = defineModuleBundle({
   meta: {
@@ -598,7 +598,7 @@ export const SupportWorkbenchBundle = defineModuleBundle({
       },
     },
   },
-});`}),d("p",{className:"text-muted-foreground text-sm",children:"Expected output: `defineModuleBundle` validates the route, surface, and verification dimensions at runtime."})]}),R("div",{className:"space-y-3",children:[d("h2",{className:"font-bold text-2xl",children:"2) Resolve the plan"}),d("p",{className:"text-muted-foreground text-sm",children:"Resolve against a real route, device, and preference profile. This is where the runtime chooses the surface, layout, bindings, and audit reasons."}),d(ie,{language:"typescript",filename:"src/runtime/resolve-support-workbench.ts",code:`import { resolveBundle } from "@contractspec/lib.surface-runtime/runtime/resolve-bundle";
+});`}),d("p",{className:"text-muted-foreground text-sm",children:"Expected output: `defineModuleBundle` validates the route, surface, and verification dimensions at runtime."})]}),O("div",{className:"space-y-3",children:[d("h2",{className:"font-bold text-2xl",children:"2) Resolve the plan"}),d("p",{className:"text-muted-foreground text-sm",children:"Resolve against a real route, device, and preference profile. This is where the runtime chooses the surface, layout, bindings, and audit reasons."}),d(de,{language:"typescript",filename:"src/runtime/resolve-support-workbench.ts",code:`import { resolveBundle } from "@contractspec/lib.surface-runtime/runtime/resolve-bundle";
 
 export const supportWorkbenchPlan = await resolveBundle(
   SupportWorkbenchBundle,
@@ -622,7 +622,7 @@ export const supportWorkbenchPlan = await resolveBundle(
     },
     capabilities: ["tickets.read", "tickets.update"],
   }
-);`}),d("p",{className:"text-muted-foreground text-sm",children:"Expected output: a `ResolvedSurfacePlan` with `bundleKey`, `surfaceId`, `layoutId`, `bindings`, `adaptation`, and audit reasons."})]}),R("div",{className:"space-y-3",children:[d("h2",{className:"font-bold text-2xl",children:"3) Render the plan"}),d("p",{className:"text-muted-foreground text-sm",children:"The host app renders the resolved plan, not the raw spec. That keeps layout selection, overlays, and AI proposals downstream of the declared bundle contract."}),d(ie,{language:"tsx",filename:"src/app/support/SurfaceHost.tsx",code:`import { BundleProvider, BundleRenderer } from "@contractspec/lib.surface-runtime/react";
+);`}),d("p",{className:"text-muted-foreground text-sm",children:"Expected output: a `ResolvedSurfacePlan` with `bundleKey`, `surfaceId`, `layoutId`, `bindings`, `adaptation`, and audit reasons."})]}),O("div",{className:"space-y-3",children:[d("h2",{className:"font-bold text-2xl",children:"3) Render the plan"}),d("p",{className:"text-muted-foreground text-sm",children:"The host app renders the resolved plan, not the raw spec. That keeps layout selection, overlays, and AI proposals downstream of the declared bundle contract."}),d(de,{language:"tsx",filename:"src/app/support/SurfaceHost.tsx",code:`import { BundleProvider, BundleRenderer } from "@contractspec/lib.surface-runtime/react";
 
 export function SurfaceHost() {
   return (
@@ -630,10 +630,10 @@ export function SurfaceHost() {
       <BundleRenderer assistantSlotId="assistant" />
     </BundleProvider>
   );
-}`}),d("p",{className:"text-muted-foreground text-sm",children:"Expected output: the route renders according to the resolved layout root and slot plan instead of bespoke page assembly."})]}),R("div",{className:"card-subtle space-y-3 p-6",children:[d("h3",{className:"font-semibold text-lg",children:"Verification checks"}),R("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[d("li",{children:"The resolved `surfaceId` matches the route you expected."}),d("li",{children:"The `layoutId` is stable for the active view and preferences."}),d("li",{children:"The plan carries audit reasons and all seven adaptation dimensions."}),d("li",{children:"Assistant or overlay work stays within declared slots."})]})]})]}),R("div",{className:"flex items-center gap-4 pt-4",children:[R(Pe,{href:"/docs/specs/module-bundles",className:"btn-primary",children:["Back to module bundles ",d(mt,{size:16})]}),d(Pe,{href:"/docs/specs/overlays",className:"btn-ghost",children:"Next: overlays"})]})]})}import{CodeBlock as j}from"@contractspec/lib.design-system";import Ae from"@contractspec/lib.ui-link";import{ChevronRight as ht}from"lucide-react";import{jsx as u,jsxs as S}from"react/jsx-runtime";function ft(){return S("div",{className:"space-y-8",children:[S("div",{className:"space-y-3",children:[u("h1",{className:"font-bold text-4xl",children:"Generate docs + client schemas"}),u("p",{className:"text-lg text-muted-foreground",children:"Generate docs and OpenAPI output from ContractSpec operations to power SDKs, docs sites, and tooling."})]}),S("div",{className:"card-subtle space-y-4 p-6",children:[u("h2",{className:"font-bold text-2xl",children:"What you'll build"}),S("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[u("li",{children:"Export docs from your specs."}),u("li",{children:"Emit OpenAPI 3.1 for client SDK generation."}),u("li",{children:"Keep outputs deterministic with CI validation."})]})]}),S("div",{className:"space-y-6",children:[S("div",{className:"space-y-3",children:[u("h2",{className:"font-bold text-2xl",children:"1) Generate docs"}),u("p",{className:"text-muted-foreground text-sm",children:"Use the generator to emit docs from your contracts."}),u(j,{language:"bash",filename:"generate-docs",code:"contractspec generate"}),S("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",u("code",{children:"Generate X doc files in generated/docs"}),"."]})]}),S("div",{className:"space-y-3",children:[u("h2",{className:"font-bold text-2xl",children:"2) Export OpenAPI"}),u("p",{className:"text-muted-foreground text-sm",children:"Export an OpenAPI document from your registry module."}),u(j,{language:"bash",filename:"openapi-export",code:"contractspec openapi export --registry ./src/contracts/registry.ts --out ./generated/openapi.json"}),S("p",{className:"text-muted-foreground text-sm",children:["Expected output:"," ",u("code",{children:"OpenAPI written to .../generated/openapi.json"}),"."]})]}),S("div",{className:"space-y-3",children:[u("h2",{className:"font-bold text-2xl",children:"3) Validate specs"}),u(j,{language:"bash",filename:"validate-specs",code:"contractspec validate"}),S("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",u("code",{children:"Validation passed"}),"."]})]}),S("div",{className:"card-subtle space-y-3 p-6",children:[u("h3",{className:"font-semibold text-lg",children:"Example package"}),u("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."}),u(j,{language:"bash",filename:"integration-hub-example",code:`contractspec examples show integration-hub
+}`}),d("p",{className:"text-muted-foreground text-sm",children:"Expected output: the route renders according to the resolved layout root and slot plan instead of bespoke page assembly."})]}),O("div",{className:"card-subtle space-y-3 p-6",children:[d("h3",{className:"font-semibold text-lg",children:"Verification checks"}),O("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[d("li",{children:"The resolved `surfaceId` matches the route you expected."}),d("li",{children:"The `layoutId` is stable for the active view and preferences."}),d("li",{children:"The plan carries audit reasons and all seven adaptation dimensions."}),d("li",{children:"Assistant or overlay work stays within declared slots."})]})]})]}),O("div",{className:"flex items-center gap-4 pt-4",children:[O(Oe,{href:"/docs/specs/module-bundles",className:"btn-primary",children:["Back to module bundles ",d(gt,{size:16})]}),d(Oe,{href:"/docs/specs/overlays",className:"btn-ghost",children:"Next: overlays"})]})]})}import{CodeBlock as te}from"@contractspec/lib.design-system";import De from"@contractspec/lib.ui-link";import{ChevronRight as vt}from"lucide-react";import{jsx as u,jsxs as I}from"react/jsx-runtime";function bt(){return I("div",{className:"space-y-8",children:[I("div",{className:"space-y-3",children:[u("h1",{className:"font-bold text-4xl",children:"Generate docs + client schemas"}),u("p",{className:"text-lg text-muted-foreground",children:"Generate docs and OpenAPI output from ContractSpec operations to power SDKs, docs sites, and tooling."})]}),I("div",{className:"card-subtle space-y-4 p-6",children:[u("h2",{className:"font-bold text-2xl",children:"What you'll build"}),I("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[u("li",{children:"Export docs from your specs."}),u("li",{children:"Emit OpenAPI 3.1 for client SDK generation."}),u("li",{children:"Keep outputs deterministic with CI validation."})]})]}),I("div",{className:"space-y-6",children:[I("div",{className:"space-y-3",children:[u("h2",{className:"font-bold text-2xl",children:"1) Generate docs"}),u("p",{className:"text-muted-foreground text-sm",children:"Use the generator to emit docs from your contracts."}),u(te,{language:"bash",filename:"generate-docs",code:"contractspec generate"}),I("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",u("code",{children:"Generate X doc files in generated/docs"}),"."]})]}),I("div",{className:"space-y-3",children:[u("h2",{className:"font-bold text-2xl",children:"2) Export OpenAPI"}),u("p",{className:"text-muted-foreground text-sm",children:"Export an OpenAPI document from your registry module."}),u(te,{language:"bash",filename:"openapi-export",code:"contractspec openapi export --registry ./src/contracts/registry.ts --out ./generated/openapi.json"}),I("p",{className:"text-muted-foreground text-sm",children:["Expected output:"," ",u("code",{children:"OpenAPI written to .../generated/openapi.json"}),"."]})]}),I("div",{className:"space-y-3",children:[u("h2",{className:"font-bold text-2xl",children:"3) Validate specs"}),u(te,{language:"bash",filename:"validate-specs",code:"contractspec validate"}),I("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",u("code",{children:"Validation passed"}),"."]})]}),I("div",{className:"card-subtle space-y-3 p-6",children:[u("h3",{className:"font-semibold text-lg",children:"Example package"}),u("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."}),u(te,{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`})]}),u(v,{title:"Want exports tied to product decisions?",body:"Studio compiles approved changes into deliverables and pushes them to your execution stack with full evidence context."})]}),S("div",{className:"flex items-center gap-4 pt-4",children:[S(Ae,{href:"/docs/guides/docs-generation-pipeline",className:"btn-primary",children:["Next: Docs pipeline ",u(ht,{size:16})]}),u(Ae,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as M}from"@contractspec/lib.design-system";import Re from"@contractspec/lib.ui-link";import{ChevronRight as gt}from"lucide-react";import{jsx as n,jsxs as N}from"react/jsx-runtime";var yt=["builder.workspace.bootstrap","builder.channel.receiveInbound","builder.blueprint.generate","builder.plan.compile","builder.preview.create","builder.preview.runHarness","builder.export.prepare","builder.export.approve","builder.export.execute"],bt=["local runtime trust and lease details","channel-action posture for mobile/operator follow-up","comparison posture and export readiness from the shared snapshot"];function vt(){return N("div",{className:"space-y-8",children:[N("div",{className:"space-y-3",children:[n("h1",{className:"font-bold text-4xl",children:"Host the Builder workbench"}),n("p",{className:"text-lg text-muted-foreground",children:"Use the reusable Builder workbench as the desktop control surface for snapshot loading, guided authoring, preview, readiness, export, and mobile review handoff."})]}),N("div",{className:"card-subtle space-y-4 p-6",children:[n("h2",{className:"font-bold text-2xl",children:"What you'll build"}),N("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[n("li",{children:"A workspace snapshot fetch path."}),n("li",{children:"A `BuilderWorkbench` host with action callbacks."}),n("li",{children:"Runtime-mode aware preview/export controls plus mobile review links."})]})]}),N("div",{className:"space-y-6",children:[N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"1) Fetch the workspace snapshot"}),n("p",{className:"text-muted-foreground text-sm",children:"The web shell already exposes a query path for the current Builder workspace snapshot. Your host should load it first, then refresh it after each successful command."}),n(M,{language:"typescript",filename:"builder-workbench-controller.ts",code:`export async function fetchBuilderSnapshot(workspaceId: string) {
+contractspec openapi export --registry ./src/contracts/registry.ts --out ./generated/openapi.json`})]}),u(N,{title:"Want exports tied to product decisions?",body:"Studio compiles approved changes into deliverables and pushes them to your execution stack with full evidence context."})]}),I("div",{className:"flex items-center gap-4 pt-4",children:[I(De,{href:"/docs/guides/docs-generation-pipeline",className:"btn-primary",children:["Next: Docs pipeline ",u(vt,{size:16})]}),u(De,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as L}from"@contractspec/lib.design-system";import Te from"@contractspec/lib.ui-link";import{ChevronRight as Nt}from"lucide-react";import{jsx as n,jsxs as w}from"react/jsx-runtime";var wt=["builder.workspace.bootstrap","builder.channel.receiveInbound","builder.blueprint.generate","builder.plan.compile","builder.preview.create","builder.preview.runHarness","builder.export.prepare","builder.export.approve","builder.export.execute"],kt=["local runtime trust and lease details","channel-action posture for mobile/operator follow-up","comparison posture and export readiness from the shared snapshot"];function Ct(){return w("div",{className:"space-y-8",children:[w("div",{className:"space-y-3",children:[n("h1",{className:"font-bold text-4xl",children:"Host the Builder workbench"}),n("p",{className:"text-lg text-muted-foreground",children:"Use the reusable Builder workbench as the desktop control surface for snapshot loading, guided authoring, preview, readiness, export, and mobile review handoff."})]}),w("div",{className:"card-subtle space-y-4 p-6",children:[n("h2",{className:"font-bold text-2xl",children:"What you'll build"}),w("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[n("li",{children:"A workspace snapshot fetch path."}),n("li",{children:"A `BuilderWorkbench` host with action callbacks."}),n("li",{children:"Runtime-mode aware preview/export controls plus mobile review links."})]})]}),w("div",{className:"space-y-6",children:[w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"1) Fetch the workspace snapshot"}),n("p",{className:"text-muted-foreground text-sm",children:"The web shell already exposes a query path for the current Builder workspace snapshot. Your host should load it first, then refresh it after each successful command."}),n(L,{language:"typescript",filename:"builder-workbench-controller.ts",code:`export async function fetchBuilderSnapshot(workspaceId: string) {
   const response = await fetch(
     \`/api/operate/builder/queries/builder.workspace.snapshot?workspaceId=\${encodeURIComponent(workspaceId)}\`,
     { cache: "no-store" }
@@ -649,7 +649,7 @@ contractspec openapi export --registry ./src/contracts/registry.ts --out ./gener
     throw new Error("Builder workspace snapshot query returned an error.");
   }
   return payload.result;
-}`}),n("p",{className:"text-muted-foreground text-sm",children:"Expected output: one `BuilderWorkspaceSnapshot` containing workspace, plan, providers, runtime targets, preview, export, mobile review state, and the operator posture needed for local trust, lease, and comparison status."})]}),N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"2) Host the workbench and refresh on action"}),n("p",{className:"text-muted-foreground text-sm",children:"The simplest host pattern is local state plus a small action wrapper that executes one Builder command and then refreshes the snapshot."}),n(M,{language:"tsx",filename:"BuilderWorkbenchHost.tsx",code:`import {
+}`}),n("p",{className:"text-muted-foreground text-sm",children:"Expected output: one `BuilderWorkspaceSnapshot` containing workspace, plan, providers, runtime targets, preview, export, mobile review state, and the operator posture needed for local trust, lease, and comparison status."})]}),w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"2) Host the workbench and refresh on action"}),n("p",{className:"text-muted-foreground text-sm",children:"The simplest host pattern is local state plus a small action wrapper that executes one Builder command and then refreshes the snapshot."}),n(L,{language:"tsx",filename:"BuilderWorkbenchHost.tsx",code:`import {
   BuilderWorkbench,
   useBuilderWorkbenchState,
 } from "@contractspec/module.builder-workbench/presentation";
@@ -680,7 +680,7 @@ async function runAction(commandKey: string, payload?: Record<string, unknown>)
   onApproveExport={() => runAction("builder.export.approve")}
   onExecuteExport={() => runAction("builder.export.execute")}
   selectedExportRuntimeMode="hybrid"
-/>;`}),n("p",{className:"text-muted-foreground text-sm",children:"Expected output: each successful action leaves the host with a fresh snapshot and keeps the workbench tabs aligned with current runtime state."})]}),N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"3) Persist Builder defaults in workspace config"}),n("p",{className:"text-muted-foreground text-sm",children:"The host should agree with the CLI and setup flows on the same control-plane defaults. For local or hybrid setups, keep the Builder API base URL, token env var, and local runtime metadata in `.contractsrc.json`."}),n(M,{language:"json",filename:".contractsrc.json",code:`{
+/>;`}),n("p",{className:"text-muted-foreground text-sm",children:"Expected output: each successful action leaves the host with a fresh snapshot and keeps the workbench tabs aligned with current runtime state."})]}),w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"3) Persist Builder defaults in workspace config"}),n("p",{className:"text-muted-foreground text-sm",children:"The host should agree with the CLI and setup flows on the same control-plane defaults. For local or hybrid setups, keep the Builder API base URL, token env var, and local runtime metadata in `.contractsrc.json`."}),n(L,{language:"json",filename:".contractsrc.json",code:`{
   "builder": {
     "enabled": true,
     "runtimeMode": "local",
@@ -695,14 +695,14 @@ async function runAction(commandKey: string, payload?: Record<string, unknown>)
       "providerIds": ["provider.codex", "provider.local.model"]
     }
   }
-}`})]}),N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"4) Bootstrap providers and routing policy explicitly"}),n("p",{className:"text-muted-foreground text-sm",children:"Builder v3 treats provider routing as policy, not heuristic. Use the workspace bootstrap command as the single managed-first setup path instead of orchestrating provider registration in the app shell."}),n(M,{language:"typescript",filename:"builder-bootstrap.ts",code:`await executeBuilderCommand({
+}`})]}),w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"4) Bootstrap providers and routing policy explicitly"}),n("p",{className:"text-muted-foreground text-sm",children:"Builder v3 treats provider routing as policy, not heuristic. Use the workspace bootstrap command as the single managed-first setup path instead of orchestrating provider registration in the app shell."}),n(L,{language:"typescript",filename:"builder-bootstrap.ts",code:`await executeBuilderCommand({
   commandKey: "builder.workspace.bootstrap",
   workspaceId,
   payload: {
     preset: "managed_mvp",
     includeLocalHelperProvider: true,
   },
-});`})]}),N("div",{className:"card-subtle space-y-3 p-6",children:[n("h3",{className:"font-semibold text-lg",children:"Common command keys"}),n("ul",{className:"space-y-2 text-muted-foreground text-sm",children:yt.map((o)=>n("li",{children:n("code",{children:o})},o))})]}),N("div",{className:"card-subtle space-y-3 p-6",children:[n("h3",{className:"font-semibold text-lg",children:"Snapshot-backed operator details"}),n("ul",{className:"space-y-2 text-muted-foreground text-sm",children:bt.map((o)=>n("li",{children:o},o))})]}),N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"5) Keep runtime mode explicit"}),n("p",{className:"text-muted-foreground text-sm",children:"Preview and export flows are runtime-mode aware. The host chooses between `managed`, `local`, and `hybrid` and passes that choice into preview or export commands instead of hiding it behind provider selection heuristics."}),n(M,{language:"typescript",filename:"runtime-mode",code:`const [selectedExportRuntimeMode, setSelectedExportRuntimeMode] =
+});`})]}),w("div",{className:"card-subtle space-y-3 p-6",children:[n("h3",{className:"font-semibold text-lg",children:"Common command keys"}),n("ul",{className:"space-y-2 text-muted-foreground text-sm",children:wt.map((o)=>n("li",{children:n("code",{children:o})},o))})]}),w("div",{className:"card-subtle space-y-3 p-6",children:[n("h3",{className:"font-semibold text-lg",children:"Snapshot-backed operator details"}),n("ul",{className:"space-y-2 text-muted-foreground text-sm",children:kt.map((o)=>n("li",{children:o},o))})]}),w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"5) Keep runtime mode explicit"}),n("p",{className:"text-muted-foreground text-sm",children:"Preview and export flows are runtime-mode aware. The host chooses between `managed`, `local`, and `hybrid` and passes that choice into preview or export commands instead of hiding it behind provider selection heuristics."}),n(L,{language:"typescript",filename:"runtime-mode",code:`const [selectedExportRuntimeMode, setSelectedExportRuntimeMode] =
   React.useState(resolveBuilderExportRuntimeMode(initialSnapshot));
 
 await executeBuilderCommand({
@@ -711,19 +711,19 @@ await executeBuilderCommand({
   payload: {
     runtimeMode: selectedExportRuntimeMode,
   },
-	});`})]}),N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"6) Link mobile review flows"}),n("p",{className:"text-muted-foreground text-sm",children:"When a patch proposal, approval ticket, or incident needs operator follow-up away from the desktop workbench, deep-link into the mobile review route instead of inventing a separate data model."}),n(M,{language:"typescript",filename:"mobile-review-path.ts",code:`export function buildBuilderMobileReviewPath(
+	});`})]}),w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"6) Link mobile review flows"}),n("p",{className:"text-muted-foreground text-sm",children:"When a patch proposal, approval ticket, or incident needs operator follow-up away from the desktop workbench, deep-link into the mobile review route instead of inventing a separate data model."}),n(L,{language:"typescript",filename:"mobile-review-path.ts",code:`export function buildBuilderMobileReviewPath(
   workspaceId: string,
   cardId: string
 ) {
   return \`/operate/builder/workspaces/\${encodeURIComponent(workspaceId)}/mobile-review/\${encodeURIComponent(cardId)}\`;
-}`}),n("p",{className:"text-muted-foreground text-sm",children:"Expected output: the same Builder workspace state stays visible from desktop workbench and mobile review surfaces."})]}),N("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"7) Keep Connect adjacent, not embedded"}),n("p",{className:"text-muted-foreground text-sm",children:"Builder owns the authoring control plane. When Builder delegates into coding repositories, enable Connect in those target workspaces for context packs, mutation verification, replay, and review packets, but do not replace Builder contracts with Connect artifacts."}),n(M,{language:"bash",filename:"connect-init.sh",code:"contractspec connect init --scope workspace"})]})]}),N("div",{className:"flex items-center gap-4 pt-4",children:[N(Re,{href:"/docs/specs/builder-control-plane",className:"btn-primary",children:["Back to Builder control plane ",n(gt,{size:16})]}),n(Re,{href:"/docs/studio",className:"btn-ghost",children:"Studio overview"})]})]})}import{CodeBlock as U}from"@contractspec/lib.design-system";import Oe from"@contractspec/lib.ui-link";import{AlertCircle as Nt,ChevronRight as wt,FileCode as kt,Scan as le,Settings as Ct}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";var St=[{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 It(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-3",children:[e("h1",{className:"font-bold text-4xl",children:"Import Existing Codebases"}),e("p",{className:"text-lg text-muted-foreground",children:"Convert your existing API endpoints into ContractSpec contracts. Auto-detect frameworks, extract schemas, and generate explicit contract definitions from your code."})]}),a("div",{className:"card-subtle space-y-4 p-6",children:[e("h2",{className:"font-bold text-2xl",children:"What you'll learn"}),a("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[e("li",{children:"How to import existing API endpoints as ContractSpec contracts."}),e("li",{children:"Framework-specific patterns and auto-detection."}),e("li",{children:"Customizing imports with scopes, dry-run, and output options."}),e("li",{children:"Registering imported contracts and adding handlers."})]})]}),a("div",{className:"space-y-6",children:[a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"Why import existing code?"}),e("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:"}),a("ul",{className:"list-disc space-y-1 pl-5 text-muted-foreground text-sm",children:[e("li",{children:"Instant spec coverage for existing APIs"}),e("li",{children:"Type-safe schemas derived from your existing types"}),e("li",{children:"A foundation to iterate and refine contracts"}),e("li",{children:"Gradual adoption without rewriting code"})]})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"Supported frameworks"}),e("div",{className:"grid gap-3 md:grid-cols-2 lg:grid-cols-3",children:St.map((o)=>a("div",{className:"flex items-start gap-3 rounded-lg border border-white/10 p-4",children:[e(kt,{className:"text-violet-400",size:18}),a("div",{className:"space-y-1",children:[e("h3",{className:"font-semibold",children:o.name}),e("p",{className:"text-muted-foreground text-xs",children:o.description}),a("code",{className:"text-violet-400 text-xs",children:["--framework ",o.flag]})]})]},o.flag))})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"1) Quick start"}),e("p",{className:"text-muted-foreground text-sm",children:"Run the import command to auto-detect your framework and extract endpoints:"}),e(U,{language:"bash",filename:"import-quickstart",code:`# Auto-detect framework and import all endpoints
+}`}),n("p",{className:"text-muted-foreground text-sm",children:"Expected output: the same Builder workspace state stays visible from desktop workbench and mobile review surfaces."})]}),w("div",{className:"space-y-3",children:[n("h2",{className:"font-bold text-2xl",children:"7) Keep Connect adjacent, not embedded"}),n("p",{className:"text-muted-foreground text-sm",children:"Builder owns the authoring control plane. When Builder delegates into coding repositories, enable Connect in those target workspaces for context packs, mutation verification, replay, and review packets, but do not replace Builder contracts with Connect artifacts."}),n(L,{language:"bash",filename:"connect-init.sh",code:"contractspec connect init --scope workspace"})]})]}),w("div",{className:"flex items-center gap-4 pt-4",children:[w(Te,{href:"/docs/specs/builder-control-plane",className:"btn-primary",children:["Back to Builder control plane ",n(Nt,{size:16})]}),n(Te,{href:"/docs/studio",className:"btn-ghost",children:"Studio overview"})]})]})}import{CodeBlock as G}from"@contractspec/lib.design-system";import Be from"@contractspec/lib.ui-link";import{AlertCircle as St,ChevronRight as It,FileCode as Et,Scan as pe,Settings as At}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";var Pt=[{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 Rt(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-3",children:[e("h1",{className:"font-bold text-4xl",children:"Import Existing Codebases"}),e("p",{className:"text-lg text-muted-foreground",children:"Convert your existing API endpoints into ContractSpec contracts. Auto-detect frameworks, extract schemas, and generate explicit contract definitions from your code."})]}),a("div",{className:"card-subtle space-y-4 p-6",children:[e("h2",{className:"font-bold text-2xl",children:"What you'll learn"}),a("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[e("li",{children:"How to import existing API endpoints as ContractSpec contracts."}),e("li",{children:"Framework-specific patterns and auto-detection."}),e("li",{children:"Customizing imports with scopes, dry-run, and output options."}),e("li",{children:"Registering imported contracts and adding handlers."})]})]}),a("div",{className:"space-y-6",children:[a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"Why import existing code?"}),e("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:"}),a("ul",{className:"list-disc space-y-1 pl-5 text-muted-foreground text-sm",children:[e("li",{children:"Instant spec coverage for existing APIs"}),e("li",{children:"Type-safe schemas derived from your existing types"}),e("li",{children:"A foundation to iterate and refine contracts"}),e("li",{children:"Gradual adoption without rewriting code"})]})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"Supported frameworks"}),e("div",{className:"grid gap-3 md:grid-cols-2 lg:grid-cols-3",children:Pt.map((o)=>a("div",{className:"flex items-start gap-3 rounded-lg border border-white/10 p-4",children:[e(Et,{className:"text-violet-400",size:18}),a("div",{className:"space-y-1",children:[e("h3",{className:"font-semibold",children:o.name}),e("p",{className:"text-muted-foreground text-xs",children:o.description}),a("code",{className:"text-violet-400 text-xs",children:["--framework ",o.flag]})]})]},o.flag))})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"1) Quick start"}),e("p",{className:"text-muted-foreground text-sm",children:"Run the import command to auto-detect your framework and extract endpoints:"}),e(G,{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`}),e("p",{className:"text-muted-foreground text-sm",children:"Expected output: A summary of endpoints found, schemas extracted, and files generated."})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"2) Framework-specific patterns"}),e("p",{className:"text-muted-foreground text-sm",children:"The import command recognizes these patterns in each framework:"})]}),a("div",{className:"space-y-3",children:[a("h3",{className:"flex items-center gap-2 font-semibold text-xl",children:[e(le,{size:18,className:"text-blue-400"}),"NestJS"]}),e(U,{language:"typescript",filename:"src/users/users.controller.ts (before)",code:`@Controller('users')
+contractspec import ./src --framework nestjs`}),e("p",{className:"text-muted-foreground text-sm",children:"Expected output: A summary of endpoints found, schemas extracted, and files generated."})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"2) Framework-specific patterns"}),e("p",{className:"text-muted-foreground text-sm",children:"The import command recognizes these patterns in each framework:"})]}),a("div",{className:"space-y-3",children:[a("h3",{className:"flex items-center gap-2 font-semibold text-xl",children:[e(pe,{size:18,className:"text-blue-400"}),"NestJS"]}),e(G,{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> {
@@ -735,7 +735,7 @@ export class UsersController {
   async createUser(@Body() dto: CreateUserDto): Promise<UserDto> {
     return this.usersService.create(dto);
   }
-}`}),a("p",{className:"text-muted-foreground text-sm",children:["Detected: ",e("code",{children:"@Controller"}),", ",e("code",{children:"@Get"}),","," ",e("code",{children:"@Post"}),", ",e("code",{children:"@Body"}),", ",e("code",{children:"@Param"}),","," ",e("code",{children:"@UseGuards"})," decorators."]})]}),a("div",{className:"space-y-3",children:[a("h3",{className:"flex items-center gap-2 font-semibold text-xl",children:[e(le,{size:18,className:"text-green-400"}),"Express"]}),e(U,{language:"typescript",filename:"src/routes/users.ts (before)",code:`const router = express.Router();
+}`}),a("p",{className:"text-muted-foreground text-sm",children:["Detected: ",e("code",{children:"@Controller"}),", ",e("code",{children:"@Get"}),","," ",e("code",{children:"@Post"}),", ",e("code",{children:"@Body"}),", ",e("code",{children:"@Param"}),","," ",e("code",{children:"@UseGuards"})," decorators."]})]}),a("div",{className:"space-y-3",children:[a("h3",{className:"flex items-center gap-2 font-semibold text-xl",children:[e(pe,{size:18,className:"text-green-400"}),"Express"]}),e(G,{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);
@@ -745,7 +745,7 @@ router.get('/users/:id', async (req, res) => {
 router.post('/users', validateBody(CreateUserSchema), async (req, res) => {
   const user = await createUser(req.body);
   res.status(201).json(user);
-});`}),a("p",{className:"text-muted-foreground text-sm",children:["Detected: ",e("code",{children:"router.get"}),", ",e("code",{children:"router.post"}),", validation middleware, Zod schemas."]})]}),a("div",{className:"space-y-3",children:[a("h3",{className:"flex items-center gap-2 font-semibold text-xl",children:[e(le,{size:18,className:"text-purple-400"}),"Next.js API Routes"]}),e(U,{language:"typescript",filename:"app/api/users/[id]/route.ts (before)",code:`export async function GET(
+});`}),a("p",{className:"text-muted-foreground text-sm",children:["Detected: ",e("code",{children:"router.get"}),", ",e("code",{children:"router.post"}),", validation middleware, Zod schemas."]})]}),a("div",{className:"space-y-3",children:[a("h3",{className:"flex items-center gap-2 font-semibold text-xl",children:[e(pe,{size:18,className:"text-purple-400"}),"Next.js API Routes"]}),e(G,{language:"typescript",filename:"app/api/users/[id]/route.ts (before)",code:`export async function GET(
   request: Request,
   { params }: { params: { id: string } }
 ) {
@@ -757,7 +757,7 @@ export async function POST(request: Request) {
   const body = await request.json();
   const user = await createUser(body);
   return Response.json(user, { status: 201 });
-}`}),a("p",{className:"text-muted-foreground text-sm",children:["Detected: ",e("code",{children:"GET"}),", ",e("code",{children:"POST"})," exports in"," ",e("code",{children:"app/api/**/route.ts"})," and ",e("code",{children:"pages/api/**/*.ts"}),"."]})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"3) Understanding generated contracts"}),e("p",{className:"text-muted-foreground text-sm",children:"The import command generates ContractSpec operations with TODO placeholders for fields it cannot infer:"}),e(U,{language:"typescript",filename:".contractspec/generated/users.operation.ts",code:`import { defineQuery, defineCommand } from "@contractspec/lib.contracts-spec";
+}`}),a("p",{className:"text-muted-foreground text-sm",children:["Detected: ",e("code",{children:"GET"}),", ",e("code",{children:"POST"})," exports in"," ",e("code",{children:"app/api/**/route.ts"})," and ",e("code",{children:"pages/api/**/*.ts"}),"."]})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"3) Understanding generated contracts"}),e("p",{className:"text-muted-foreground text-sm",children:"The import command generates ContractSpec operations with TODO placeholders for fields it cannot infer:"}),e(G,{language:"typescript",filename:".contractspec/generated/users.operation.ts",code:`import { defineQuery, defineCommand } from "@contractspec/lib.contracts-spec";
 import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
 
 export const GetUserQuery = defineQuery({
@@ -817,7 +817,7 @@ export const CreateUserCommand = defineCommand({
   transport: {
     rest: { method: "POST", path: "/users" },
   },
-});`})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"4) Customizing imports"}),a("div",{className:"flex items-center gap-2",children:[e(Ct,{size:18,className:"text-violet-400"}),e("h3",{className:"font-semibold text-lg",children:"Available options"})]}),e("div",{className:"overflow-x-auto",children:a("table",{className:"w-full text-sm",children:[e("thead",{children:a("tr",{className:"border-white/10 border-b",children:[e("th",{className:"py-2 pr-4 text-left",children:"Option"}),e("th",{className:"py-2 pr-4 text-left",children:"Description"}),e("th",{className:"py-2 text-left",children:"Example"})]})}),a("tbody",{className:"text-muted-foreground",children:[a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--scope"})}),e("td",{className:"py-2 pr-4",children:"Limit to specific directories"}),e("td",{className:"py-2",children:e("code",{children:"--scope src/users src/auth"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--framework"})}),e("td",{className:"py-2 pr-4",children:"Force a specific framework"}),e("td",{className:"py-2",children:e("code",{children:"--framework express"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--output"})}),e("td",{className:"py-2 pr-4",children:"Output directory"}),e("td",{className:"py-2",children:e("code",{children:"--output ./contracts"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--dry-run"})}),e("td",{className:"py-2 pr-4",children:"Preview without writing files"}),e("td",{className:"py-2",children:e("code",{children:"--dry-run"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--analyze"})}),e("td",{className:"py-2 pr-4",children:"Analysis only, no code generation"}),e("td",{className:"py-2",children:e("code",{children:"--analyze"})})]}),a("tr",{children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--json"})}),e("td",{className:"py-2 pr-4",children:"Output as JSON for scripting"}),e("td",{className:"py-2",children:e("code",{children:"--json"})})]})]})]})}),e(U,{language:"bash",filename:"import-options",code:`# Import only specific modules
+});`})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"4) Customizing imports"}),a("div",{className:"flex items-center gap-2",children:[e(At,{size:18,className:"text-violet-400"}),e("h3",{className:"font-semibold text-lg",children:"Available options"})]}),e("div",{className:"overflow-x-auto",children:a("table",{className:"w-full text-sm",children:[e("thead",{children:a("tr",{className:"border-white/10 border-b",children:[e("th",{className:"py-2 pr-4 text-left",children:"Option"}),e("th",{className:"py-2 pr-4 text-left",children:"Description"}),e("th",{className:"py-2 text-left",children:"Example"})]})}),a("tbody",{className:"text-muted-foreground",children:[a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--scope"})}),e("td",{className:"py-2 pr-4",children:"Limit to specific directories"}),e("td",{className:"py-2",children:e("code",{children:"--scope src/users src/auth"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--framework"})}),e("td",{className:"py-2 pr-4",children:"Force a specific framework"}),e("td",{className:"py-2",children:e("code",{children:"--framework express"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--output"})}),e("td",{className:"py-2 pr-4",children:"Output directory"}),e("td",{className:"py-2",children:e("code",{children:"--output ./contracts"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--dry-run"})}),e("td",{className:"py-2 pr-4",children:"Preview without writing files"}),e("td",{className:"py-2",children:e("code",{children:"--dry-run"})})]}),a("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--analyze"})}),e("td",{className:"py-2 pr-4",children:"Analysis only, no code generation"}),e("td",{className:"py-2",children:e("code",{children:"--analyze"})})]}),a("tr",{children:[e("td",{className:"py-2 pr-4",children:e("code",{children:"--json"})}),e("td",{className:"py-2 pr-4",children:"Output as JSON for scripting"}),e("td",{className:"py-2",children:e("code",{children:"--json"})})]})]})]})}),e(G,{language:"bash",filename:"import-options",code:`# Import only specific modules
 contractspec import ./src --scope src/users src/orders
 
 # Preview with analysis
@@ -827,7 +827,7 @@ contractspec import ./src --dry-run --analyze
 contractspec import ./src --output ./src/contracts/generated
 
 # Get JSON for CI/scripting
-contractspec import ./src --json > import-result.json`})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"5) Registering imported contracts"}),e("p",{className:"text-muted-foreground text-sm",children:"After import, register contracts and add handlers:"}),e(U,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
+contractspec import ./src --json > import-result.json`})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"5) Registering imported contracts"}),e("p",{className:"text-muted-foreground text-sm",children:"After import, register contracts and add handlers:"}),e(G,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
   OperationSpecRegistry,
   installOp,
 } from "@contractspec/lib.contracts-spec/operations";
@@ -847,8 +847,8 @@ installOp(registry, GetUserQuery, async (input) => {
 installOp(registry, CreateUserCommand, async (input) => {
   const user = await db.user.create({ data: input });
   return { id: user.id };
-});`})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"6) After importing"}),a("ol",{className:"list-decimal space-y-2 pl-5 text-muted-foreground text-sm",children:[a("li",{children:[e("strong",{children:"Review generated contracts"})," — Check the TODO placeholders and fill in descriptions, owners, and tags."]}),a("li",{children:[e("strong",{children:"Refine schemas"})," — Add proper types, validation rules, and error definitions."]}),a("li",{children:[e("strong",{children:"Run validation"})," —"," ",e("code",{children:"contractspec validate"})," to ensure contracts are valid."]}),a("li",{children:[e("strong",{children:"Register and wire handlers"})," — Connect contracts to your existing business logic."]}),a("li",{children:[e("strong",{children:"Iterate"})," — The imported contracts are a starting point. Refine them as your spec matures."]})]})]}),a("div",{className:"space-y-3",children:[a("h2",{className:"flex items-center gap-2 font-bold text-2xl",children:[e(Nt,{size:20,className:"text-yellow-400"}),"Troubleshooting"]}),a("div",{className:"space-y-4",children:[a("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Framework not detected"}),a("p",{className:"text-muted-foreground text-sm",children:["Use ",e("code",{children:"--framework <name>"})," to force a specific framework. Check that your entry files follow standard patterns."]})]}),a("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Missing schemas"}),a("p",{className:"text-muted-foreground text-sm",children:["Schema inference works best with explicit types. If using"," ",e("code",{children:"any"})," or dynamic types, you'll see TODO placeholders. Fill them in manually."]})]}),a("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Partial imports"}),a("p",{className:"text-muted-foreground text-sm",children:["Some endpoints may not be detected if they use unconventional patterns. Use ",e("code",{children:"--analyze"})," to see what was found, then add missing contracts manually."]})]})]})]}),e(v,{title:"Want evidence-driven migration priorities?",body:"Studio clusters product signals into scored patterns, then proposes contract changes and execution-ready work for the highest-impact areas."})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[a(Oe,{href:"/docs/guides/spec-validation-and-typing",className:"btn-primary",children:["Next: Spec validation + typing ",e(wt,{size:16})]}),e(Oe,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as q}from"@contractspec/lib.design-system";import Te from"@contractspec/lib.ui-link";import{ChevronRight as Et}from"lucide-react";import{jsx as s,jsxs as g}from"react/jsx-runtime";function Pt(){return g("div",{className:"space-y-8",children:[g("div",{className:"space-y-3",children:[s("h1",{className:"font-bold text-4xl",children:"Next.js: add one endpoint"}),s("p",{className:"text-lg text-muted-foreground",children:"Add ContractSpec to an existing Next.js App Router project by wiring a single operation end-to-end with validation and types."})]}),g("div",{className:"card-subtle space-y-4 p-6",children:[s("h2",{className:"font-bold text-2xl",children:"What you'll build"}),g("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[s("li",{children:"One OperationSpec with SchemaModel validation."}),s("li",{children:"A registry wiring the operation to its handler."}),s("li",{children:"A Next.js route handler that exposes the operation."})]})]}),g("div",{className:"space-y-6",children:[g("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"1) Install core packages"}),s(q,{language:"bash",filename:"nextjs-install",code:`bun add -D contractspec
-bun add @contractspec/lib.contracts-spec @contractspec/lib.contracts-runtime-server-rest @contractspec/lib.schema`}),g("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",s("code",{children:"added 3 packages"})," and a lockfile update."]})]}),g("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"2) Define the operation spec"}),g("p",{className:"text-muted-foreground text-sm",children:["Create ",s("code",{children:"src/contracts/healthcheck.operation.ts"}),":"]}),s(q,{language:"typescript",filename:"src/contracts/healthcheck.operation.ts",code:`import { defineQuery } from "@contractspec/lib.contracts-spec/operations";
+});`})]}),a("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"6) After importing"}),a("ol",{className:"list-decimal space-y-2 pl-5 text-muted-foreground text-sm",children:[a("li",{children:[e("strong",{children:"Review generated contracts"})," — Check the TODO placeholders and fill in descriptions, owners, and tags."]}),a("li",{children:[e("strong",{children:"Refine schemas"})," — Add proper types, validation rules, and error definitions."]}),a("li",{children:[e("strong",{children:"Run validation"})," —"," ",e("code",{children:"contractspec validate"})," to ensure contracts are valid."]}),a("li",{children:[e("strong",{children:"Register and wire handlers"})," — Connect contracts to your existing business logic."]}),a("li",{children:[e("strong",{children:"Iterate"})," — The imported contracts are a starting point. Refine them as your spec matures."]})]})]}),a("div",{className:"space-y-3",children:[a("h2",{className:"flex items-center gap-2 font-bold text-2xl",children:[e(St,{size:20,className:"text-yellow-400"}),"Troubleshooting"]}),a("div",{className:"space-y-4",children:[a("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Framework not detected"}),a("p",{className:"text-muted-foreground text-sm",children:["Use ",e("code",{children:"--framework <name>"})," to force a specific framework. Check that your entry files follow standard patterns."]})]}),a("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Missing schemas"}),a("p",{className:"text-muted-foreground text-sm",children:["Schema inference works best with explicit types. If using"," ",e("code",{children:"any"})," or dynamic types, you'll see TODO placeholders. Fill them in manually."]})]}),a("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Partial imports"}),a("p",{className:"text-muted-foreground text-sm",children:["Some endpoints may not be detected if they use unconventional patterns. Use ",e("code",{children:"--analyze"})," to see what was found, then add missing contracts manually."]})]})]})]}),e(N,{title:"Want evidence-driven migration priorities?",body:"Studio clusters product signals into scored patterns, then proposes contract changes and execution-ready work for the highest-impact areas."})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[a(Be,{href:"/docs/guides/spec-validation-and-typing",className:"btn-primary",children:["Next: Spec validation + typing ",e(It,{size:16})]}),e(Be,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as F}from"@contractspec/lib.design-system";import Me from"@contractspec/lib.ui-link";import{ChevronRight as Ot}from"lucide-react";import{jsx as s,jsxs as y}from"react/jsx-runtime";function Dt(){return y("div",{className:"space-y-8",children:[y("div",{className:"space-y-3",children:[s("h1",{className:"font-bold text-4xl",children:"Next.js: add one endpoint"}),s("p",{className:"text-lg text-muted-foreground",children:"Add ContractSpec to an existing Next.js App Router project by wiring a single operation end-to-end with validation and types."})]}),y("div",{className:"card-subtle space-y-4 p-6",children:[s("h2",{className:"font-bold text-2xl",children:"What you'll build"}),y("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[s("li",{children:"One OperationSpec with SchemaModel validation."}),s("li",{children:"A registry wiring the operation to its handler."}),s("li",{children:"A Next.js route handler that exposes the operation."})]})]}),y("div",{className:"space-y-6",children:[y("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"1) Install core packages"}),s(F,{language:"bash",filename:"nextjs-install",code:`bun add -D contractspec
+bun add @contractspec/lib.contracts-spec @contractspec/lib.contracts-runtime-server-rest @contractspec/lib.schema`}),y("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",s("code",{children:"added 3 packages"})," and a lockfile update."]})]}),y("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"2) Define the operation spec"}),y("p",{className:"text-muted-foreground text-sm",children:["Create ",s("code",{children:"src/contracts/healthcheck.operation.ts"}),":"]}),s(F,{language:"typescript",filename:"src/contracts/healthcheck.operation.ts",code:`import { defineQuery } from "@contractspec/lib.contracts-spec/operations";
 import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
 
 const HealthcheckOutput = new SchemaModel({
@@ -879,7 +879,7 @@ export const HealthcheckQuery = defineQuery({
     gql: { field: "healthcheck_get" },
     mcp: { toolName: "healthcheck_get-v1" },
   },
-});`})]}),g("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"3) Register the operation"}),g("p",{className:"text-muted-foreground text-sm",children:["Create ",s("code",{children:"src/contracts/registry.ts"}),":"]}),s(q,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
+});`})]}),y("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"3) Register the operation"}),y("p",{className:"text-muted-foreground text-sm",children:["Create ",s("code",{children:"src/contracts/registry.ts"}),":"]}),s(F,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
   OperationSpecRegistry,
   installOp,
 } from "@contractspec/lib.contracts-spec/operations";
@@ -890,7 +890,7 @@ export const registry = new OperationSpecRegistry();
 installOp(registry, HealthcheckQuery, async () => ({
   status: "ok",
   checkedAt: new Date().toISOString(),
-}));`})]}),g("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"4) Add the Next.js handler"}),g("p",{className:"text-muted-foreground text-sm",children:["Create ",s("code",{children:"app/api/ops/[...route]/route.ts"}),":"]}),s(q,{language:"typescript",filename:"app/api/ops/[...route]/route.ts",code:`import { makeNextAppHandler } from "@contractspec/lib.contracts-runtime-server-rest/rest-next-app";
+}));`})]}),y("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"4) Add the Next.js handler"}),y("p",{className:"text-muted-foreground text-sm",children:["Create ",s("code",{children:"app/api/ops/[...route]/route.ts"}),":"]}),s(F,{language:"typescript",filename:"app/api/ops/[...route]/route.ts",code:`import { makeNextAppHandler } from "@contractspec/lib.contracts-runtime-server-rest/rest-next-app";
 import { registry } from "@/contracts/registry";
 
 const handler = makeNextAppHandler(registry, async () => ({
@@ -898,11 +898,82 @@ const handler = makeNextAppHandler(registry, async () => ({
   tenantId: "public",
 }));
 
-export { handler as GET, handler as POST };`}),g("p",{className:"text-muted-foreground text-sm",children:["Expected output: the route responds at",s("code",{children:" /api/ops/healthcheck.get"}),"."]})]}),g("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"5) Validate the spec"}),s(q,{language:"bash",filename:"nextjs-validate",code:"contractspec validate src/contracts/healthcheck.operation.ts"}),g("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",s("code",{children:"Validation passed"}),"."]})]}),g("div",{className:"card-subtle space-y-3 p-6",children:[s("h3",{className:"font-semibold text-lg",children:"Example package"}),g("p",{className:"text-muted-foreground text-sm",children:["Use ",s("code",{children:"@contractspec/example.lifecycle-dashboard"})," as a lightweight Next.js snippet reference."]}),s(q,{language:"bash",filename:"nextjs-example",code:`# Inspect the example docs
+export { handler as GET, handler as POST };`}),y("p",{className:"text-muted-foreground text-sm",children:["Expected output: the route responds at",s("code",{children:" /api/ops/healthcheck.get"}),"."]})]}),y("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"5) Validate the spec"}),s(F,{language:"bash",filename:"nextjs-validate",code:"contractspec validate src/contracts/healthcheck.operation.ts"}),y("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",s("code",{children:"Validation passed"}),"."]})]}),y("div",{className:"card-subtle space-y-3 p-6",children:[s("h3",{className:"font-semibold text-lg",children:"Example package"}),y("p",{className:"text-muted-foreground text-sm",children:["Use ",s("code",{children:"@contractspec/example.lifecycle-dashboard"})," as a lightweight Next.js snippet reference."]}),s(F,{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 .`})]}),s(v,{title:"Want real product evidence behind endpoint changes?",body:"Studio correlates meetings, support, analytics, and code signals before compiling endpoint decisions into spec diffs."})]}),g("div",{className:"flex items-center gap-4 pt-4",children:[g(Te,{href:"/docs/guides/spec-validation-and-typing",className:"btn-primary",children:["Next: Spec validation + typing ",s(Et,{size:16})]}),s(Te,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as ee}from"@contractspec/lib.design-system";import Be from"@contractspec/lib.ui-link";import{ChevronRight as At}from"lucide-react";import{jsx as p,jsxs as I}from"react/jsx-runtime";var Rt=["root `README.md` and generated root `AGENTS.md` inputs when contributor or operator workflow changes","the nearest package `README.md` and `AGENTS.md` for any touched public package surface","website docs and `/llms*` summaries when the release changes how users or contributors should work"];function Ot(){return I("div",{className:"space-y-8",children:[I("div",{className:"space-y-3",children:[p("h1",{className:"font-bold text-4xl",children:"Author release capsules"}),p("p",{className:"text-lg text-muted-foreground",children:"Pair each publishable changeset with a structured release capsule so changelog, upgrade, and docs surfaces all read from the same release source of truth."})]}),I("div",{className:"card-subtle space-y-4 p-6",children:[p("h2",{className:"font-bold text-2xl",children:"What you'll build"}),I("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[I("li",{children:["A ",p("code",{children:".changeset/<slug>.md"})," file for package/version intent."]}),I("li",{children:["A ",p("code",{children:".changeset/<slug>.release.yaml"})," companion for audiences, migrations, validation, and evidence."]}),p("li",{children:"Generated release artifacts that the website changelog and upgrade flows can consume safely."})]})]}),I("div",{className:"space-y-6",children:[I("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"1) Create the paired changeset files"}),p("p",{className:"text-muted-foreground text-sm",children:"The Markdown file states the package bumps and reader-facing change intent. The YAML file carries the structured release metadata."}),p(ee,{language:"yaml",filename:".changeset/contract-dx-first-slice.release.yaml",code:`schemaVersion: "1"
+contractspec examples validate --repo-root .`})]}),s(N,{title:"Want real product evidence behind endpoint changes?",body:"Studio correlates meetings, support, analytics, and code signals before compiling endpoint decisions into spec diffs."})]}),y("div",{className:"flex items-center gap-4 pt-4",children:[y(Me,{href:"/docs/guides/spec-validation-and-typing",className:"btn-primary",children:["Next: Spec validation + typing ",s(Ot,{size:16})]}),s(Me,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as ae}from"@contractspec/lib.design-system";import Ue from"@contractspec/lib.ui-link";import{ChevronRight as Tt}from"lucide-react";import{jsx as h,jsxs as D}from"react/jsx-runtime";var Bt=["ProviderDeltaSyncState persisted for each source after sync or watch renewal.","Tombstoned provider records are skipped before indexing or mutation.","Outbound mutations carry dry-run, approval, idempotency, audit, and send-gate evidence.","Connect adoption resolves existing knowledge and integration surfaces before new runtime code is added."];function Mt(){return D("div",{className:"space-y-8",children:[D("div",{className:"space-y-3",children:[h("h1",{className:"font-bold text-4xl",children:"Adopt provider-backed knowledge"}),h("p",{className:"text-lg text-muted-foreground",children:"Turn Gmail and Google Drive into queryable knowledge without hiding provider state, webhook expiry, or mutation risk in background jobs. The contract layer models the source, the integration layer models provider deltas, and the knowledge runtime owns ingestion/query orchestration."})]}),D("div",{className:"card-subtle space-y-4 p-6",children:[h("h2",{className:"font-bold text-2xl",children:"What you'll build"}),D("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[h("li",{children:"Gmail and Drive sources bound to explicit knowledge spaces."}),h("li",{children:"A checkpoint store for leases, cursors, webhook channel expiry, and replay evidence."}),h("li",{children:"A mutation gate that blocks unsafe external sends or provider writes."}),h("li",{children:"Connect adoption evidence proving you reused the existing ContractSpec surfaces before adding custom provider code."})]})]}),D("div",{className:"space-y-6",children:[D("section",{className:"space-y-3",children:[h("h2",{className:"font-bold text-2xl",children:"1) Start from specs and sources"}),h("p",{className:"text-muted-foreground text-sm",children:"Define the knowledge space and source binding before runtime sync. Provider credentials stay in integration connections; source config stores only identity, scope, and replayable sync state."}),h(ae,{language:"typescript",filename:"knowledge-source.ts",code:`const source = {
+  meta: {
+    id: "src_drive_support",
+    tenantId: "tenant-acme",
+    integrationConnectionId: "conn_google_drive",
+    spaceKey: "knowledge.support-faq",
+    spaceVersion: "1.0.0",
+    label: "Support Drive",
+    sourceType: "google_drive",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  },
+  syncState: {
+    cursorId: "drive-start-page-token",
+    watermarkVersion: "drive-v1",
+    lease: {
+      holder: "knowledge-sync-worker",
+      expiresAt: new Date(Date.now() + 5 * 60_000),
+      renewalWindowMs: 60_000,
+    },
+  },
+  config: {
+    query: "mimeType = 'text/plain' and trashed = false",
+  },
+};`})]}),D("section",{className:"space-y-3",children:[h("h2",{className:"font-bold text-2xl",children:"2) Sync with checkpoints, not blind polling"}),h("p",{className:"text-muted-foreground text-sm",children:"`KnowledgeRuntime` can load a stored provider delta before listing Gmail or Drive, then save the next checkpoint after indexing. The store can be a database table, workflow state, or Connect-backed replay artifact."}),h(ae,{language:"typescript",filename:"knowledge-runtime.ts",code:`const knowledge = createKnowledgeRuntime({
+  collection: "knowledge-support",
+  namespace: "tenant-acme",
+  embeddings,
+  vectorStore,
+  gmail,
+  drive,
+  deltaCheckpointStore,
+});
+
+await knowledge.syncGmail(
+  { label: "support" },
+  { sourceId: "src_gmail_support", evidenceRef: "audit://sync/gmail" },
+);
+
+await knowledge.syncDriveFiles(
+  { query: "mimeType = 'text/plain' and trashed = false" },
+  { sourceId: "src_drive_support", evidenceRef: "audit://sync/drive" },
+);
+
+await knowledge.watchDriveChanges(
+  {
+    channelId: "drive-watch-support",
+    webhookUrl: "https://app.example.com/webhooks/google-drive",
+  },
+  { sourceId: "src_drive_support" },
+);`})]}),D("section",{className:"space-y-3",children:[h("h2",{className:"font-bold text-2xl",children:"3) Gate mutations before provider writes"}),h("p",{className:"text-muted-foreground text-sm",children:"External sends and provider mutations should produce a decision envelope whether they execute, block, or run as dry-run. Persist that envelope with the same audit trail as the provider checkpoint."}),h(ae,{language:"typescript",filename:"governed-mutation.ts",code:`const result = await knowledge.runGovernedMutation(
+  {
+    operation: "gmail.message.send",
+    sourceId: "src_gmail_support",
+    requiresApproval: true,
+    outboundSend: true,
+    governance: {
+      idempotencyKey: "tenant:gmail-send:123",
+      auditEvidence: { evidenceRef: "audit://gmail-send/123" },
+      approvalRefs: [{ id: "approval-123" }],
+      outboundSendGate: {
+        status: "approved",
+        evidenceRef: "gate://gmail-send/123",
+      },
+    },
+  },
+  () => gmail.sendEmail(message),
+  { audit: (envelope) => auditTrail.write(envelope) },
+);`})]}),D("section",{className:"card-subtle space-y-3 p-6",children:[h("h2",{className:"font-bold text-2xl",children:"4) Adoption evidence"}),h("ul",{className:"space-y-2 text-muted-foreground text-sm",children:Bt.map((o)=>h("li",{children:o},o))}),h(ae,{language:"bash",filename:"connect-adoption",code:`contractspec connect adoption sync --json
+
+printf '{"goal":"Wire provider-backed knowledge for Gmail and Drive"}' | \\
+  contractspec connect adoption resolve --family knowledge --stdin --json`})]})]}),D("div",{className:"flex items-center gap-4 pt-4",children:[h(Ue,{href:"/docs/knowledge/sources",className:"btn-ghost",children:"Knowledge sources"}),D(Ue,{href:"/docs/integrations/google-drive",className:"btn-primary",children:["Google Drive integration ",h(Tt,{size:16})]})]})]})}import{CodeBlock as oe}from"@contractspec/lib.design-system";import Le from"@contractspec/lib.ui-link";import{ChevronRight as Ut}from"lucide-react";import{jsx as p,jsxs as E}from"react/jsx-runtime";var Lt=["root `README.md` and generated root `AGENTS.md` inputs when contributor or operator workflow changes","the nearest package `README.md` and `AGENTS.md` for any touched public package surface","website docs and `/llms*` summaries when the release changes how users or contributors should work"];function Gt(){return E("div",{className:"space-y-8",children:[E("div",{className:"space-y-3",children:[p("h1",{className:"font-bold text-4xl",children:"Author release capsules"}),p("p",{className:"text-lg text-muted-foreground",children:"Pair each publishable changeset with a structured release capsule so changelog, upgrade, and docs surfaces all read from the same release source of truth."})]}),E("div",{className:"card-subtle space-y-4 p-6",children:[p("h2",{className:"font-bold text-2xl",children:"What you'll build"}),E("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[E("li",{children:["A ",p("code",{children:".changeset/<slug>.md"})," file for package/version intent."]}),E("li",{children:["A ",p("code",{children:".changeset/<slug>.release.yaml"})," companion for audiences, migrations, validation, and evidence."]}),p("li",{children:"Generated release artifacts that the website changelog and upgrade flows can consume safely."})]})]}),E("div",{className:"space-y-6",children:[E("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"1) Create the paired changeset files"}),p("p",{className:"text-muted-foreground text-sm",children:"The Markdown file states the package bumps and reader-facing change intent. The YAML file carries the structured release metadata."}),p(oe,{language:"yaml",filename:".changeset/contract-dx-first-slice.release.yaml",code:`schemaVersion: "1"
 slug: contract-dx-first-slice
 summary: Improve app-config, theme, and feature authoring with explicit validation and shared setup alignment.
 isBreaking: false
@@ -913,10 +984,10 @@ validation:
   commands:
     - "cd packages/libs/contracts-spec && bun run test && bun run typecheck"
   evidence:
-    - "Package-level validation entrypoints now back setup, docs, and CLI authoring flows."`}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: every publishable slug has both the human-facing changeset and the structured release capsule beside it."})]}),I("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"2) Use the release authoring commands instead of raw drift-prone edits"}),p(ee,{language:"bash",filename:"release-authoring",code:`contractspec release init --summary "Improve app-config, theme, and feature authoring"
+    - "Package-level validation entrypoints now back setup, docs, and CLI authoring flows."`}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: every publishable slug has both the human-facing changeset and the structured release capsule beside it."})]}),E("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"2) Use the release authoring commands instead of raw drift-prone edits"}),p(oe,{language:"bash",filename:"release-authoring",code:`contractspec release init --summary "Improve app-config, theme, and feature authoring"
 
 # Or revise an existing capsule with the guided flow
-contractspec release edit contract-dx-first-slice`}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: the CLI scaffolds or revises the paired files with the current release schema instead of leaving maintainers to hand-roll YAML structure."})]}),I("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"3) Build the generated release artifacts before consuming them"}),p(ee,{language:"bash",filename:"release-build",code:"contractspec release build"}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: `generated/releases/manifest.json`, `generated/releases/upgrade-manifest.json`, and the related customer/maintainer guidance files are refreshed from the release capsules."})]}),I("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"4) Enforce completeness before publishing or building the changelog"}),p(ee,{language:"bash",filename:"release-check",code:"contractspec release check --strict"}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: missing capsules, incomplete migration guidance, or stale generated release artifacts are flagged before the website changelog or publish workflow treats the release data as canonical."})]}),I("div",{className:"card-subtle space-y-3 p-6",children:[p("h3",{className:"font-semibold text-lg",children:"5) Sync the public docs if workflow expectations changed"}),p("ul",{className:"space-y-2 text-muted-foreground text-sm",children:Rt.map((o)=>p("li",{children:o},o))})]})]}),I("div",{className:"flex items-center gap-4 pt-4",children:[I(Be,{href:"/docs/guides/connect-in-a-repo",className:"btn-primary",children:["Connect guide ",p(At,{size:16})]}),p(Be,{href:"/changelog",className:"btn-ghost",children:"Website changelog"})]})]})}import{CodeBlock as te}from"@contractspec/lib.design-system";import De from"@contractspec/lib.ui-link";import{ChevronRight as Tt}from"lucide-react";import{jsx as f,jsxs as P}from"react/jsx-runtime";function Bt(){return P("div",{className:"space-y-8",children:[P("div",{className:"space-y-3",children:[f("h1",{className:"font-bold text-4xl",children:"Spec-driven validation + typing"}),f("p",{className:"text-lg text-muted-foreground",children:"Define a single operation with SchemaModel, generate validation, and keep your existing handler logic."})]}),P("div",{className:"card-subtle space-y-4 p-6",children:[f("h2",{className:"font-bold text-2xl",children:"What you'll build"}),P("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[f("li",{children:"One command spec with explicit input/output models."}),f("li",{children:"Validation + typing without rewriting your service layer."}),f("li",{children:"Clear acceptance scenarios for regression safety."})]})]}),P("div",{className:"space-y-6",children:[P("div",{className:"space-y-3",children:[f("h2",{className:"font-bold text-2xl",children:"1) Define the spec"}),P("p",{className:"text-muted-foreground text-sm",children:["Create ",f("code",{children:"src/contracts/contact-create.operation.ts"}),":"]}),f(te,{language:"typescript",filename:"src/contracts/contact-create.operation.ts",code:`import { defineCommand } from "@contractspec/lib.contracts-spec/operations";
+contractspec release edit contract-dx-first-slice`}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: the CLI scaffolds or revises the paired files with the current release schema instead of leaving maintainers to hand-roll YAML structure."})]}),E("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"3) Build the generated release artifacts before consuming them"}),p(oe,{language:"bash",filename:"release-build",code:"contractspec release build"}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: `generated/releases/manifest.json`, `generated/releases/upgrade-manifest.json`, and the related customer/maintainer guidance files are refreshed from the release capsules."})]}),E("div",{className:"space-y-3",children:[p("h2",{className:"font-bold text-2xl",children:"4) Enforce completeness before publishing or building the changelog"}),p(oe,{language:"bash",filename:"release-check",code:"contractspec release check --strict"}),p("p",{className:"text-muted-foreground text-sm",children:"Expected output: missing capsules, incomplete migration guidance, or stale generated release artifacts are flagged before the website changelog or publish workflow treats the release data as canonical."})]}),E("div",{className:"card-subtle space-y-3 p-6",children:[p("h3",{className:"font-semibold text-lg",children:"5) Sync the public docs if workflow expectations changed"}),p("ul",{className:"space-y-2 text-muted-foreground text-sm",children:Lt.map((o)=>p("li",{children:o},o))})]})]}),E("div",{className:"flex items-center gap-4 pt-4",children:[E(Le,{href:"/docs/guides/connect-in-a-repo",className:"btn-primary",children:["Connect guide ",p(Ut,{size:16})]}),p(Le,{href:"/changelog",className:"btn-ghost",children:"Website changelog"})]})]})}import{CodeBlock as re}from"@contractspec/lib.design-system";import Ge from"@contractspec/lib.ui-link";import{ChevronRight as Wt}from"lucide-react";import{jsx as g,jsxs as P}from"react/jsx-runtime";function _t(){return P("div",{className:"space-y-8",children:[P("div",{className:"space-y-3",children:[g("h1",{className:"font-bold text-4xl",children:"Spec-driven validation + typing"}),g("p",{className:"text-lg text-muted-foreground",children:"Define a single operation with SchemaModel, generate validation, and keep your existing handler logic."})]}),P("div",{className:"card-subtle space-y-4 p-6",children:[g("h2",{className:"font-bold text-2xl",children:"What you'll build"}),P("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[g("li",{children:"One command spec with explicit input/output models."}),g("li",{children:"Validation + typing without rewriting your service layer."}),g("li",{children:"Clear acceptance scenarios for regression safety."})]})]}),P("div",{className:"space-y-6",children:[P("div",{className:"space-y-3",children:[g("h2",{className:"font-bold text-2xl",children:"1) Define the spec"}),P("p",{className:"text-muted-foreground text-sm",children:["Create ",g("code",{children:"src/contracts/contact-create.operation.ts"}),":"]}),g(re,{language:"typescript",filename:"src/contracts/contact-create.operation.ts",code:`import { defineCommand } from "@contractspec/lib.contracts-spec/operations";
 import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
 
 const ContactInput = new SchemaModel({
@@ -962,7 +1033,7 @@ export const ContactCreateCommand = defineCommand({
       },
     ],
   },
-});`})]}),P("div",{className:"space-y-3",children:[f("h2",{className:"font-bold text-2xl",children:"2) Wire the handler"}),f("p",{className:"text-muted-foreground text-sm",children:"Keep your existing code. Just ensure the handler returns the output shape defined above."}),f(te,{language:"typescript",filename:"src/handlers/contact-create.ts",code:`import { ContactCreateCommand } from "@/contracts/contact-create.operation";
+});`})]}),P("div",{className:"space-y-3",children:[g("h2",{className:"font-bold text-2xl",children:"2) Wire the handler"}),g("p",{className:"text-muted-foreground text-sm",children:"Keep your existing code. Just ensure the handler returns the output shape defined above."}),g(re,{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"],
@@ -974,15 +1045,15 @@ export const ContactCreateCommand = defineCommand({
      email: input.email,
      createdAt: new Date().toISOString(),
    };
- }`})]}),P("div",{className:"space-y-3",children:[f("h2",{className:"font-bold text-2xl",children:"3) Validate"}),f(te,{language:"bash",filename:"spec-validation",code:"contractspec validate src/contracts/contact-create.operation.ts"}),P("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",f("code",{children:"Validation passed"}),"."]})]}),P("div",{className:"card-subtle space-y-3 p-6",children:[f("h3",{className:"font-semibold text-lg",children:"Example package"}),f("p",{className:"text-muted-foreground text-sm",children:"The CRM Pipeline example includes real specs, handlers, and presentations for contact + deal flows."}),f(te,{language:"bash",filename:"crm-example",code:`# Build + validate the CRM pipeline example
+ }`})]}),P("div",{className:"space-y-3",children:[g("h2",{className:"font-bold text-2xl",children:"3) Validate"}),g(re,{language:"bash",filename:"spec-validation",code:"contractspec validate src/contracts/contact-create.operation.ts"}),P("p",{className:"text-muted-foreground text-sm",children:["Expected output: ",g("code",{children:"Validation passed"}),"."]})]}),P("div",{className:"card-subtle space-y-3 p-6",children:[g("h3",{className:"font-semibold text-lg",children:"Example package"}),g("p",{className:"text-muted-foreground text-sm",children:"The CRM Pipeline example includes real specs, handlers, and presentations for contact + deal flows."}),g(re,{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`})]}),f(v,{title:"Need validation tied to real outcomes?",body:"Studio links checks to evidence, focus decisions, and post-release verification so specs evolve with product truth."})]}),P("div",{className:"flex items-center gap-4 pt-4",children:[P(De,{href:"/docs/guides/contract-driven-forms",className:"btn-primary",children:["Next: Contract-driven forms ",f(Tt,{size:16})]}),f(De,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as Dt}from"@contractspec/lib.design-system";import{HStack as se,VStack as $}from"@contractspec/lib.design-system/layout";import{List as Mt,ListItem as de}from"@contractspec/lib.design-system/list";import{H1 as Ut,H2 as Lt,P as Me,Text as G}from"@contractspec/lib.design-system/typography";import Wt from"@contractspec/lib.ui-link";import{ArrowRight as Ft,CheckCircle2 as qt,GitBranch as Gt}from"lucide-react";import{jsx as b,jsxs as T}from"react/jsx-runtime";var zt=[{title:"Adopt one endpoint in Next.js",description:"Start inside a live app with one operation, one generated surface, and one clearly bounded change.",href:"/docs/guides/nextjs-one-endpoint",time:"25 min"},{title:"Import an existing codebase",description:"Stabilize what already exists instead of treating adoption as a rewrite project.",href:"/docs/guides/import-existing-codebases",time:"20 min"},{title:"Validation and typing",description:"Keep runtime validation and TypeScript behavior aligned from the same source definitions.",href:"/docs/guides/spec-validation-and-typing",time:"20 min"},{title:"Build a contract-driven form",description:"Use FormSpec to keep data shape, fields, layout, policy, and submit behavior aligned.",href:"/docs/guides/contract-driven-forms",time:"25 min"},{title:"Flexible import templates",description:"Accept partner CSV, JSON, and XML files with alternate headers and localized values while preserving a canonical import contract.",href:"/docs/guides/data-exchange-import-templates",time:"25 min"},{title:"Generate docs and clients",description:"Publish stable docs, schemas, and client-facing artifacts from the contract layer.",href:"/docs/guides/generate-docs-clients-schemas",time:"20 min"},{title:"Docs pipeline",description:"Feed generated reference material into the docs site without confusing ownership.",href:"/docs/guides/docs-generation-pipeline",time:"20 min"},{title:"Build a first module bundle",description:"Define one bundle spec, resolve a surface plan, and render it through the React host layer.",href:"/docs/guides/first-module-bundle",time:"20 min"},{title:"Host the Builder workbench",description:"Wire a Builder workspace snapshot, common commands, runtime modes, and mobile review links into the reusable host.",href:"/docs/guides/host-builder-workbench",time:"20 min"},{title:"Use Connect in a repo",description:"Enable Connect, verify agent actions locally, and inspect the resulting review and replay artifacts.",href:"/docs/guides/connect-in-a-repo",time:"15 min"},{title:"Author release capsules",description:"Pair changesets with structured release capsules and generate the artifacts that changelog and upgrade flows consume.",href:"/docs/guides/release-capsules",time:"15 min"},{title:"CI diff gating",description:"Use deterministic checks to catch drift and risky changes before they ship.",href:"/docs/guides/ci-contract-diff-gating",time:"15 min"}];function _t(){return T($,{className:"space-y-10",children:[T($,{className:"space-y-3",children:[b(G,{className:"editorial-kicker",children:"Build"}),b(Ut,{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Adoption guides for teams that want to keep their code."}),b(Me,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"These guides assume you are introducing ContractSpec into a real code base. Start with a narrow surface, verify the generated outputs, and expand only after the contract loop feels trustworthy."})]}),b($,{className:"grid gap-4 md:grid-cols-2",children:zt.map((o)=>T(Wt,{href:o.href,className:"editorial-panel",children:[T(se,{className:"flex items-start justify-between gap-4",children:[T($,{children:[b(Lt,{className:"font-semibold text-xl",children:o.title}),b(Me,{className:"mt-2 text-muted-foreground text-sm leading-7",children:o.description})]}),b(Ft,{className:"mt-1 shrink-0",size:18})]}),T(se,{className:"mt-4 flex items-center gap-2 text-muted-foreground text-xs",children:[b(qt,{size:14}),T(G,{children:["Target time: ",o.time]})]})]},o.href))}),T($,{className:"editorial-panel space-y-4",children:[T(se,{className:"flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]",children:[b(Gt,{size:16}),b(G,{children:"Working style"})]}),T(Mt,{className:"editorial-list",children:[b(de,{children:b(G,{children:"Run each guide in a branch or sandboxed workspace."})}),b(de,{children:b(G,{children:"Prefer one bounded surface at a time: one endpoint, one workflow, one integration, one unsafe module."})}),b(de,{children:b(G,{children:"Use the example and reference outputs to verify what changed, not just the narrative page."})})]}),b(Dt,{language:"bash",filename:"guides-quickstart",code:`# list example systems
+bun run validate`})]}),g(N,{title:"Need validation tied to real outcomes?",body:"Studio links checks to evidence, focus decisions, and post-release verification so specs evolve with product truth."})]}),P("div",{className:"flex items-center gap-4 pt-4",children:[P(Ge,{href:"/docs/guides/contract-driven-forms",className:"btn-primary",children:["Next: Contract-driven forms ",g(Wt,{size:16})]}),g(Ge,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}import{CodeBlock as qt}from"@contractspec/lib.design-system";import{HStack as me,VStack as Z}from"@contractspec/lib.design-system/layout";import{List as Ft,ListItem as ue}from"@contractspec/lib.design-system/list";import{H1 as zt,H2 as Kt,P as We,Text as z}from"@contractspec/lib.design-system/typography";import Qt from"@contractspec/lib.ui-link";import{ArrowRight as Jt,CheckCircle2 as Yt,GitBranch as $t}from"lucide-react";import{jsx as b,jsxs as B}from"react/jsx-runtime";var Xt=[{title:"Adopt one endpoint in Next.js",description:"Start inside a live app with one operation, one generated surface, and one clearly bounded change.",href:"/docs/guides/nextjs-one-endpoint",time:"25 min"},{title:"Import an existing codebase",description:"Stabilize what already exists instead of treating adoption as a rewrite project.",href:"/docs/guides/import-existing-codebases",time:"20 min"},{title:"Validation and typing",description:"Keep runtime validation and TypeScript behavior aligned from the same source definitions.",href:"/docs/guides/spec-validation-and-typing",time:"20 min"},{title:"Build a contract-driven form",description:"Use FormSpec to keep data shape, fields, layout, policy, and submit behavior aligned.",href:"/docs/guides/contract-driven-forms",time:"25 min"},{title:"Flexible import templates",description:"Accept partner CSV, JSON, and XML files with alternate headers and localized values while preserving a canonical import contract.",href:"/docs/guides/data-exchange-import-templates",time:"25 min"},{title:"Generate docs and clients",description:"Publish stable docs, schemas, and client-facing artifacts from the contract layer.",href:"/docs/guides/generate-docs-clients-schemas",time:"20 min"},{title:"Docs pipeline",description:"Feed generated reference material into the docs site without confusing ownership.",href:"/docs/guides/docs-generation-pipeline",time:"20 min"},{title:"Build a first module bundle",description:"Define one bundle spec, resolve a surface plan, and render it through the React host layer.",href:"/docs/guides/first-module-bundle",time:"20 min"},{title:"Host the Builder workbench",description:"Wire a Builder workspace snapshot, common commands, runtime modes, and mobile review links into the reusable host.",href:"/docs/guides/host-builder-workbench",time:"20 min"},{title:"Use Connect in a repo",description:"Enable Connect, verify agent actions locally, and inspect the resulting review and replay artifacts.",href:"/docs/guides/connect-in-a-repo",time:"15 min"},{title:"Adopt provider-backed knowledge",description:"Sync Gmail and Google Drive into governed knowledge spaces with provider checkpoints, tombstones, and mutation gates.",href:"/docs/guides/provider-backed-knowledge",time:"30 min"},{title:"Author release capsules",description:"Pair changesets with structured release capsules and generate the artifacts that changelog and upgrade flows consume.",href:"/docs/guides/release-capsules",time:"15 min"},{title:"CI diff gating",description:"Use deterministic checks to catch drift and risky changes before they ship.",href:"/docs/guides/ci-contract-diff-gating",time:"15 min"}];function Zt(){return B(Z,{className:"space-y-10",children:[B(Z,{className:"space-y-3",children:[b(z,{className:"editorial-kicker",children:"Build"}),b(zt,{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Adoption guides for teams that want to keep their code."}),b(We,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"These guides assume you are introducing ContractSpec into a real code base. Start with a narrow surface, verify the generated outputs, and expand only after the contract loop feels trustworthy."})]}),b(Z,{className:"grid gap-4 md:grid-cols-2",children:Xt.map((o)=>B(Qt,{href:o.href,className:"editorial-panel",children:[B(me,{className:"flex items-start justify-between gap-4",children:[B(Z,{children:[b(Kt,{className:"font-semibold text-xl",children:o.title}),b(We,{className:"mt-2 text-muted-foreground text-sm leading-7",children:o.description})]}),b(Jt,{className:"mt-1 shrink-0",size:18})]}),B(me,{className:"mt-4 flex items-center gap-2 text-muted-foreground text-xs",children:[b(Yt,{size:14}),B(z,{children:["Target time: ",o.time]})]})]},o.href))}),B(Z,{className:"editorial-panel space-y-4",children:[B(me,{className:"flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]",children:[b($t,{size:16}),b(z,{children:"Working style"})]}),B(Ft,{className:"editorial-list",children:[b(ue,{children:b(z,{children:"Run each guide in a branch or sandboxed workspace."})}),b(ue,{children:b(z,{children:"Prefer one bounded surface at a time: one endpoint, one workflow, one integration, one unsafe module."})}),b(ue,{children:b(z,{children:"Use the example and reference outputs to verify what changed, not just the narrative page."})})]}),b(qt,{language:"bash",filename:"guides-quickstart",code:`# list example systems
 contractspec examples list
 
 # validate the examples in this workspace
-contractspec examples validate --repo-root .`})]})]})}import{registerDocBlocks as Kt}from"@contractspec/lib.contracts-spec/docs";var Qt=[{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
+contractspec examples validate --repo-root .`})]})]})}import{registerDocBlocks as Vt}from"@contractspec/lib.contracts-spec/docs";var Ht=[{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)
 
@@ -1030,4 +1101,13 @@ bun docs:generate -- --version v1.0.0
 
 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.`}];Kt(Qt);export{_t as GuidesIndexPage,Bt as GuideSpecValidationTypingPage,Ot as GuideReleaseCapsulesPage,Pt as GuideNextjsOneEndpointPage,It as GuideImportExistingCodebasesPage,vt as GuideHostBuilderWorkbenchPage,ft as GuideGenerateDocsClientsSchemasPage,ut as GuideFirstModuleBundlePage,pt as GuideDocsPipelinePage,st as GuideDataExchangeImportTemplatesPage,ot as GuideContractTypesPage,He as GuideContractDrivenFormsPage,Je as GuideConnectInRepoPage,_e as GuideCIDiffGatingPage};
+Run ContractSpec CI checks to detect drift and breaking changes before merge.`},{id:"docs.guides.provider-backed-knowledge",title:"Adopt provider-backed knowledge",summary:"Ingest Gmail and Google Drive with persisted deltas, replay checkpoints, tombstones, and mutation governance.",kind:"usage",visibility:"public",route:"/docs/guides/provider-backed-knowledge",tags:["guides","knowledge","integrations","governance"],body:`# Adopt provider-backed knowledge
+
+Use \`@contractspec/lib.knowledge\` with Gmail and Google Drive providers to sync external knowledge through explicit \`ProviderDeltaSyncState\` checkpoints.
+
+## Production baseline
+
+- Persist provider cursor, watermark, webhook, replay, dedupe, idempotency, and tombstone state per source.
+- Register \`knowledge.mutation.evaluateGovernance\` for mutation approval and audit evidence.
+- Gate outbound sends and provider mutations through dry-run, approval, idempotency, and audit checks.
+- Keep Connect review packets tied to the provider source and mutation evidence refs.`}];Vt(Ht);export{Zt as GuidesIndexPage,_t as GuideSpecValidationTypingPage,Gt as GuideReleaseCapsulesPage,Mt as GuideProviderBackedKnowledgePage,Dt as GuideNextjsOneEndpointPage,Rt as GuideImportExistingCodebasesPage,Ct as GuideHostBuilderWorkbenchPage,bt as GuideGenerateDocsClientsSchemasPage,yt as GuideFirstModuleBundlePage,ft as GuideDocsPipelinePage,ut as GuideDataExchangeImportTemplatesPage,it as GuideContractTypesPage,et as GuideContractDrivenFormsPage,Ze as GuideConnectInRepoPage,Ye as GuideCIDiffGatingPage};