@contractspec/bundle.library 3.7.6 → 3.8.2

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

@@ -3,16 +3,16 @@
 import Link from "@contractspec/lib.ui-link";
 import { jsx, jsxs } from "react/jsx-runtime";
 function StudioPrompt({
-  title = "Want to turn product signals into spec-first deliverables?",
-  body = "ContractSpec Studio ingests evidence from meetings, support, analytics, docs, and code, then compiles decisions into spec diffs and task packs.",
-  ctaLabel = "Try Studio",
-  href = "https://www.contractspec.studio"
+  title = "Need the operating layer on top of OSS ContractSpec?",
+  body = "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 = "See what Studio adds",
+  href = "https://www.contractspec.studio/docs"
 }) {
   return /* @__PURE__ */ jsxs("div", {
     className: "card-subtle space-y-3 p-6",
     children: [
       /* @__PURE__ */ jsx("h3", {
-        className: "text-lg font-semibold",
+        className: "font-semibold text-lg",
         children: title
       }),
       /* @__PURE__ */ jsx("p", {
@@ -32,11 +32,11 @@ function StudioPrompt({
 import { CodeBlock } from "@contractspec/lib.design-system";
 import Link2 from "@contractspec/lib.ui-link";
 import {
+  AlertCircle,
   ChevronRight,
   FileCode,
   Scan,
-  Settings,
-  AlertCircle
+  Settings
 } from "lucide-react";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 var supportedFrameworks = [
@@ -84,12 +84,12 @@ function GuideImportExistingCodebasesPage() {
         className: "space-y-3",
         children: [
           /* @__PURE__ */ jsx2("h1", {
-            className: "text-4xl font-bold",
+            className: "font-bold text-4xl",
             children: "Import Existing Codebases"
           }),
           /* @__PURE__ */ jsx2("p", {
-            className: "text-muted-foreground text-lg",
-            children: "Convert your existing API endpoints into ContractSpec contracts. Auto-detect frameworks, extract schemas, and generate spec-first definitions from your code."
+            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."
           })
         ]
       }),
@@ -97,11 +97,11 @@ function GuideImportExistingCodebasesPage() {
         className: "card-subtle space-y-4 p-6",
         children: [
           /* @__PURE__ */ jsx2("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "What you'll learn"
           }),
           /* @__PURE__ */ jsxs2("ul", {
-            className: "text-muted-foreground space-y-2 text-sm",
+            className: "space-y-2 text-muted-foreground text-sm",
             children: [
               /* @__PURE__ */ jsx2("li", {
                 children: "How to import existing API endpoints as ContractSpec contracts."
@@ -126,7 +126,7 @@ function GuideImportExistingCodebasesPage() {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "Why import existing code?"
               }),
               /* @__PURE__ */ jsx2("p", {
@@ -134,7 +134,7 @@ function GuideImportExistingCodebasesPage() {
                 children: "Instead of writing contracts from scratch, the import command extracts endpoint patterns from your existing codebase. This gives you:"
               }),
               /* @__PURE__ */ jsxs2("ul", {
-                className: "text-muted-foreground list-disc space-y-1 pl-5 text-sm",
+                className: "list-disc space-y-1 pl-5 text-muted-foreground text-sm",
                 children: [
                   /* @__PURE__ */ jsx2("li", {
                     children: "Instant spec coverage for existing APIs"
@@ -156,7 +156,7 @@ function GuideImportExistingCodebasesPage() {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "Supported frameworks"
               }),
               /* @__PURE__ */ jsx2("div", {
@@ -180,7 +180,7 @@ function GuideImportExistingCodebasesPage() {
                           children: fw.description
                         }),
                         /* @__PURE__ */ jsxs2("code", {
-                          className: "text-xs text-violet-400",
+                          className: "text-violet-400 text-xs",
                           children: [
                             "--framework ",
                             fw.flag
@@ -197,7 +197,7 @@ function GuideImportExistingCodebasesPage() {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "1) Quick start"
               }),
               /* @__PURE__ */ jsx2("p", {
@@ -226,7 +226,7 @@ contractspec import ./src --framework nestjs`
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "2) Framework-specific patterns"
               }),
               /* @__PURE__ */ jsx2("p", {
@@ -239,7 +239,7 @@ contractspec import ./src --framework nestjs`
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsxs2("h3", {
-                className: "flex items-center gap-2 text-xl font-semibold",
+                className: "flex items-center gap-2 font-semibold text-xl",
                 children: [
                   /* @__PURE__ */ jsx2(Scan, {
                     size: 18,
@@ -303,7 +303,7 @@ export class UsersController {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsxs2("h3", {
-                className: "flex items-center gap-2 text-xl font-semibold",
+                className: "flex items-center gap-2 font-semibold text-xl",
                 children: [
                   /* @__PURE__ */ jsx2(Scan, {
                     size: 18,
@@ -347,7 +347,7 @@ router.post('/users', validateBody(CreateUserSchema), async (req, res) => {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsxs2("h3", {
-                className: "flex items-center gap-2 text-xl font-semibold",
+                className: "flex items-center gap-2 font-semibold text-xl",
                 children: [
                   /* @__PURE__ */ jsx2(Scan, {
                     size: 18,
@@ -402,7 +402,7 @@ export async function POST(request: Request) {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "3) Understanding generated contracts"
               }),
               /* @__PURE__ */ jsx2("p", {
@@ -480,7 +480,7 @@ export const CreateUserCommand = defineCommand({
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "4) Customizing imports"
               }),
               /* @__PURE__ */ jsxs2("div", {
@@ -491,7 +491,7 @@ export const CreateUserCommand = defineCommand({
                     className: "text-violet-400"
                   }),
                   /* @__PURE__ */ jsx2("h3", {
-                    className: "text-lg font-semibold",
+                    className: "font-semibold text-lg",
                     children: "Available options"
                   })
                 ]
@@ -503,7 +503,7 @@ export const CreateUserCommand = defineCommand({
                   children: [
                     /* @__PURE__ */ jsx2("thead", {
                       children: /* @__PURE__ */ jsxs2("tr", {
-                        className: "border-b border-white/10",
+                        className: "border-white/10 border-b",
                         children: [
                           /* @__PURE__ */ jsx2("th", {
                             className: "py-2 pr-4 text-left",
@@ -524,7 +524,7 @@ export const CreateUserCommand = defineCommand({
                       className: "text-muted-foreground",
                       children: [
                         /* @__PURE__ */ jsxs2("tr", {
-                          className: "border-b border-white/5",
+                          className: "border-white/5 border-b",
                           children: [
                             /* @__PURE__ */ jsx2("td", {
                               className: "py-2 pr-4",
@@ -545,7 +545,7 @@ export const CreateUserCommand = defineCommand({
                           ]
                         }),
                         /* @__PURE__ */ jsxs2("tr", {
-                          className: "border-b border-white/5",
+                          className: "border-white/5 border-b",
                           children: [
                             /* @__PURE__ */ jsx2("td", {
                               className: "py-2 pr-4",
@@ -566,7 +566,7 @@ export const CreateUserCommand = defineCommand({
                           ]
                         }),
                         /* @__PURE__ */ jsxs2("tr", {
-                          className: "border-b border-white/5",
+                          className: "border-white/5 border-b",
                           children: [
                             /* @__PURE__ */ jsx2("td", {
                               className: "py-2 pr-4",
@@ -587,7 +587,7 @@ export const CreateUserCommand = defineCommand({
                           ]
                         }),
                         /* @__PURE__ */ jsxs2("tr", {
-                          className: "border-b border-white/5",
+                          className: "border-white/5 border-b",
                           children: [
                             /* @__PURE__ */ jsx2("td", {
                               className: "py-2 pr-4",
@@ -608,7 +608,7 @@ export const CreateUserCommand = defineCommand({
                           ]
                         }),
                         /* @__PURE__ */ jsxs2("tr", {
-                          className: "border-b border-white/5",
+                          className: "border-white/5 border-b",
                           children: [
                             /* @__PURE__ */ jsx2("td", {
                               className: "py-2 pr-4",
@@ -674,7 +674,7 @@ contractspec import ./src --json > import-result.json`
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "5) Registering imported contracts"
               }),
               /* @__PURE__ */ jsx2("p", {
@@ -712,11 +712,11 @@ installOp(registry, CreateUserCommand, async (input) => {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "6) After importing"
               }),
               /* @__PURE__ */ jsxs2("ol", {
-                className: "text-muted-foreground list-decimal space-y-2 pl-5 text-sm",
+                className: "list-decimal space-y-2 pl-5 text-muted-foreground text-sm",
                 children: [
                   /* @__PURE__ */ jsxs2("li", {
                     children: [
@@ -771,7 +771,7 @@ installOp(registry, CreateUserCommand, async (input) => {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsxs2("h2", {
-                className: "flex items-center gap-2 text-2xl font-bold",
+                className: "flex items-center gap-2 font-bold text-2xl",
                 children: [
                   /* @__PURE__ */ jsx2(AlertCircle, {
                     size: 20,
@@ -847,7 +847,7 @@ installOp(registry, CreateUserCommand, async (input) => {
           }),
           /* @__PURE__ */ jsx2(StudioPrompt, {
             title: "Want evidence-driven migration priorities?",
-            body: "Studio clusters product signals into scored patterns, then proposes spec-first change cards for the highest-impact areas."
+            body: "Studio clusters product signals into scored patterns, then proposes contract changes and execution-ready work for the highest-impact areas."
           })
         ]
       }),

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

@@ -3,16 +3,16 @@
 import Link from "@contractspec/lib.ui-link";
 import { jsx, jsxs } from "react/jsx-runtime";
 function StudioPrompt({
-  title = "Want to turn product signals into spec-first deliverables?",
-  body = "ContractSpec Studio ingests evidence from meetings, support, analytics, docs, and code, then compiles decisions into spec diffs and task packs.",
-  ctaLabel = "Try Studio",
-  href = "https://www.contractspec.studio"
+  title = "Need the operating layer on top of OSS ContractSpec?",
+  body = "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 = "See what Studio adds",
+  href = "https://www.contractspec.studio/docs"
 }) {
   return /* @__PURE__ */ jsxs("div", {
     className: "card-subtle space-y-3 p-6",
     children: [
       /* @__PURE__ */ jsx("h3", {
-        className: "text-lg font-semibold",
+        className: "font-semibold text-lg",
         children: title
       }),
       /* @__PURE__ */ jsx("p", {
@@ -41,11 +41,11 @@ function GuideNextjsOneEndpointPage() {
         className: "space-y-3",
         children: [
           /* @__PURE__ */ jsx2("h1", {
-            className: "text-4xl font-bold",
+            className: "font-bold text-4xl",
             children: "Next.js: add one endpoint"
           }),
           /* @__PURE__ */ jsx2("p", {
-            className: "text-muted-foreground text-lg",
+            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."
           })
         ]
@@ -54,11 +54,11 @@ function GuideNextjsOneEndpointPage() {
         className: "card-subtle space-y-4 p-6",
         children: [
           /* @__PURE__ */ jsx2("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "What you'll build"
           }),
           /* @__PURE__ */ jsxs2("ul", {
-            className: "text-muted-foreground space-y-2 text-sm",
+            className: "space-y-2 text-muted-foreground text-sm",
             children: [
               /* @__PURE__ */ jsx2("li", {
                 children: "One OperationSpec with SchemaModel validation."
@@ -80,7 +80,7 @@ function GuideNextjsOneEndpointPage() {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "1) Install core packages"
               }),
               /* @__PURE__ */ jsx2(CodeBlock, {
@@ -105,7 +105,7 @@ bun add @contractspec/lib.contracts-spec @contractspec/lib.contracts-runtime-ser
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "2) Define the operation spec"
               }),
               /* @__PURE__ */ jsxs2("p", {
@@ -160,7 +160,7 @@ export const HealthcheckQuery = defineQuery({
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "3) Register the operation"
               }),
               /* @__PURE__ */ jsxs2("p", {
@@ -195,7 +195,7 @@ installOp(registry, HealthcheckQuery, async () => ({
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "4) Add the Next.js handler"
               }),
               /* @__PURE__ */ jsxs2("p", {
@@ -237,7 +237,7 @@ export { handler as GET, handler as POST };`
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "5) Validate the spec"
               }),
               /* @__PURE__ */ jsx2(CodeBlock, {
@@ -261,7 +261,7 @@ export { handler as GET, handler as POST };`
             className: "card-subtle space-y-3 p-6",
             children: [
               /* @__PURE__ */ jsx2("h3", {
-                className: "text-lg font-semibold",
+                className: "font-semibold text-lg",
                 children: "Example package"
               }),
               /* @__PURE__ */ jsxs2("p", {

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

@@ -3,16 +3,16 @@
 import Link from "@contractspec/lib.ui-link";
 import { jsx, jsxs } from "react/jsx-runtime";
 function StudioPrompt({
-  title = "Want to turn product signals into spec-first deliverables?",
-  body = "ContractSpec Studio ingests evidence from meetings, support, analytics, docs, and code, then compiles decisions into spec diffs and task packs.",
-  ctaLabel = "Try Studio",
-  href = "https://www.contractspec.studio"
+  title = "Need the operating layer on top of OSS ContractSpec?",
+  body = "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 = "See what Studio adds",
+  href = "https://www.contractspec.studio/docs"
 }) {
   return /* @__PURE__ */ jsxs("div", {
     className: "card-subtle space-y-3 p-6",
     children: [
       /* @__PURE__ */ jsx("h3", {
-        className: "text-lg font-semibold",
+        className: "font-semibold text-lg",
         children: title
       }),
       /* @__PURE__ */ jsx("p", {
@@ -41,11 +41,11 @@ function GuideSpecValidationTypingPage() {
         className: "space-y-3",
         children: [
           /* @__PURE__ */ jsx2("h1", {
-            className: "text-4xl font-bold",
+            className: "font-bold text-4xl",
             children: "Spec-driven validation + typing"
           }),
           /* @__PURE__ */ jsx2("p", {
-            className: "text-muted-foreground text-lg",
+            className: "text-lg text-muted-foreground",
             children: "Define a single operation with SchemaModel, generate validation, and keep your existing handler logic."
           })
         ]
@@ -54,11 +54,11 @@ function GuideSpecValidationTypingPage() {
         className: "card-subtle space-y-4 p-6",
         children: [
           /* @__PURE__ */ jsx2("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "What you'll build"
           }),
           /* @__PURE__ */ jsxs2("ul", {
-            className: "text-muted-foreground space-y-2 text-sm",
+            className: "space-y-2 text-muted-foreground text-sm",
             children: [
               /* @__PURE__ */ jsx2("li", {
                 children: "One command spec with explicit input/output models."
@@ -80,7 +80,7 @@ function GuideSpecValidationTypingPage() {
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "1) Define the spec"
               }),
               /* @__PURE__ */ jsxs2("p", {
@@ -150,7 +150,7 @@ export const ContactCreateCommand = defineCommand({
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "2) Wire the handler"
               }),
               /* @__PURE__ */ jsx2("p", {
@@ -180,7 +180,7 @@ export const ContactCreateCommand = defineCommand({
             className: "space-y-3",
             children: [
               /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+                className: "font-bold text-2xl",
                 children: "3) Validate"
               }),
               /* @__PURE__ */ jsx2(CodeBlock, {
@@ -204,7 +204,7 @@ export const ContactCreateCommand = defineCommand({
             className: "card-subtle space-y-3 p-6",
             children: [
               /* @__PURE__ */ jsx2("h3", {
-                className: "text-lg font-semibold",
+                className: "font-semibold text-lg",
                 children: "Example package"
               }),
               /* @__PURE__ */ jsx2("p", {

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

@@ -2,48 +2,42 @@
 // src/components/docs/guides/GuidesIndexPage.tsx
 import { CodeBlock } from "@contractspec/lib.design-system";
 import Link from "@contractspec/lib.ui-link";
-import { ArrowRight, BookOpen, CheckCircle2 } from "lucide-react";
+import { ArrowRight, CheckCircle2, GitBranch } from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
 var guides = [
   {
-    title: "Contract types overview",
-    description: "Learn about the different contract types and when to use each one.",
-    href: "/docs/guides/contract-types",
-    time: "15 min"
-  },
-  {
-    title: "Next.js: one endpoint",
-    description: "Add ContractSpec to an existing Next.js app by wiring one operation end-to-end.",
+    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 existing codebases",
-    description: "Convert your existing API endpoints into ContractSpec contracts for fast onboarding.",
+    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: "Spec-driven validation + typing",
-    description: "Define operations with SchemaModel, generate types, and enforce validation without rewrites.",
+    title: "Validation and typing",
+    description: "Keep runtime validation and TypeScript behavior aligned from the same source definitions.",
     href: "/docs/guides/spec-validation-and-typing",
     time: "20 min"
   },
   {
-    title: "Generate docs + client schemas",
-    description: "Export docs and OpenAPI for client SDKs and tooling from your specs.",
+    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: "Wire generated docs into a reference site with a chunked index.",
+    description: "Feed generated reference material into the docs site without confusing ownership.",
     href: "/docs/guides/docs-generation-pipeline",
     time: "20 min"
   },
   {
-    title: "CI gating with deterministic diffs",
-    description: "Add ContractSpec CI checks to gate breaking changes and drift.",
+    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"
   }
@@ -55,13 +49,17 @@ function GuidesIndexPage() {
       /* @__PURE__ */ jsxs("div", {
         className: "space-y-3",
         children: [
+          /* @__PURE__ */ jsx("p", {
+            className: "editorial-kicker",
+            children: "Build"
+          }),
           /* @__PURE__ */ jsx("h1", {
-            className: "text-4xl font-bold",
-            children: "Guides"
+            className: "font-serif text-4xl tracking-[-0.04em] md:text-5xl",
+            children: "Adoption guides for teams that want to keep their code."
           }),
           /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground text-lg",
-            children: "Hands-on guides with commands, expected output, and CI-verified example packages."
+            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."
           })
         ]
       }),
@@ -69,27 +67,31 @@ function GuidesIndexPage() {
         className: "grid gap-4 md:grid-cols-2",
         children: guides.map((guide) => /* @__PURE__ */ jsxs(Link, {
           href: guide.href,
-          className: "card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50",
+          className: "editorial-panel",
           children: [
             /* @__PURE__ */ jsxs("div", {
-              className: "flex items-center justify-between",
+              className: "flex items-start justify-between gap-4",
               children: [
-                /* @__PURE__ */ jsx("h2", {
-                  className: "text-xl font-semibold transition-colors group-hover:text-violet-400",
-                  children: guide.title
+                /* @__PURE__ */ jsxs("div", {
+                  children: [
+                    /* @__PURE__ */ jsx("h2", {
+                      className: "font-semibold text-xl",
+                      children: guide.title
+                    }),
+                    /* @__PURE__ */ jsx("p", {
+                      className: "mt-2 text-muted-foreground text-sm leading-7",
+                      children: guide.description
+                    })
+                  ]
                 }),
                 /* @__PURE__ */ jsx(ArrowRight, {
-                  className: "text-violet-400",
+                  className: "mt-1 shrink-0",
                   size: 18
                 })
               ]
             }),
-            /* @__PURE__ */ jsx("p", {
-              className: "text-muted-foreground text-sm",
-              children: guide.description
-            }),
             /* @__PURE__ */ jsxs("div", {
-              className: "text-muted-foreground flex items-center gap-2 text-xs",
+              className: "mt-4 flex items-center gap-2 text-muted-foreground text-xs",
               children: [
                 /* @__PURE__ */ jsx(CheckCircle2, {
                   size: 14
@@ -106,38 +108,59 @@ function GuidesIndexPage() {
         }, guide.href))
       }),
       /* @__PURE__ */ jsxs("div", {
-        className: "card-subtle space-y-4 p-6",
+        className: "editorial-panel space-y-4",
         children: [
           /* @__PURE__ */ jsxs("div", {
-            className: "flex items-center gap-2 text-sm font-semibold tracking-[0.2em] text-violet-400 uppercase",
+            className: "flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]",
             children: [
-              /* @__PURE__ */ jsx(BookOpen, {
+              /* @__PURE__ */ jsx(GitBranch, {
                 size: 16
               }),
-              "How to use the guides"
+              "Working style"
             ]
           }),
           /* @__PURE__ */ jsxs("ul", {
-            className: "text-muted-foreground space-y-2 text-sm",
+            className: "editorial-list",
             children: [
-              /* @__PURE__ */ jsx("li", {
-                children: "Run each guide in a fresh branch or sandbox workspace."
+              /* @__PURE__ */ jsxs("li", {
+                children: [
+                  /* @__PURE__ */ jsx("span", {
+                    className: "editorial-list-marker"
+                  }),
+                  /* @__PURE__ */ jsx("span", {
+                    children: "Run each guide in a branch or sandboxed workspace."
+                  })
+                ]
               }),
-              /* @__PURE__ */ jsx("li", {
-                children: "Use the linked example package to validate end-to-end."
+              /* @__PURE__ */ jsxs("li", {
+                children: [
+                  /* @__PURE__ */ jsx("span", {
+                    className: "editorial-list-marker"
+                  }),
+                  /* @__PURE__ */ jsx("span", {
+                    children: "Prefer one bounded surface at a time: one endpoint, one workflow, one integration, one unsafe module."
+                  })
+                ]
               }),
-              /* @__PURE__ */ jsx("li", {
-                children: "Keep the commands as written to match CI expectations."
+              /* @__PURE__ */ jsxs("li", {
+                children: [
+                  /* @__PURE__ */ jsx("span", {
+                    className: "editorial-list-marker"
+                  }),
+                  /* @__PURE__ */ jsx("span", {
+                    children: "Use the example and reference outputs to verify what changed, not just the narrative page."
+                  })
+                ]
               })
             ]
           }),
           /* @__PURE__ */ jsx(CodeBlock, {
             language: "bash",
             filename: "guides-quickstart",
-            code: `# list all examples
+            code: `# list example systems
 contractspec examples list
 
-# validate example packages in this repo
+# validate the examples in this workspace
 contractspec examples validate --repo-root .`
           })
         ]