@contractspec/bundle.library 3.7.5 → 3.7.7

package/dist/node/components/docs/DocsIndexPage.js

@@ -1,264 +1,911 @@
+// src/components/docs/docsManifest.ts
+var DOCS_PRIMARY_SECTIONS = [
+  {
+    key: "start",
+    title: "Start",
+    description: "Install ContractSpec, wire a first contract, and adopt it into an existing codebase."
+  },
+  {
+    key: "core-model",
+    title: "Core Model",
+    description: "Learn how contracts, generated surfaces, policies, overlays, and safe regeneration fit together."
+  },
+  {
+    key: "build",
+    title: "Build",
+    description: "Use practical guides, libraries, architecture patterns, and examples to ship real surfaces."
+  },
+  {
+    key: "operate",
+    title: "Operate",
+    description: "Run the system safely with governance, auditability, tracing, and operator-grade controls."
+  },
+  {
+    key: "integrations",
+    title: "Integrations",
+    description: "Connect models, messaging, storage, payments, search, and external systems through typed bindings."
+  },
+  {
+    key: "reference",
+    title: "Reference",
+    description: "Search generated contract docs, inspect example packages, and navigate the system as source of truth."
+  },
+  {
+    key: "studio",
+    title: "Studio",
+    description: "Understand what Studio adds on top of the open system and when to adopt it."
+  }
+];
+var DOCS_PAGES = [
+  {
+    href: "/docs",
+    title: "Documentation",
+    description: "OSS-first documentation for ContractSpec, the open spec system for AI-native software.",
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/getting-started/start-here",
+    title: "Start here",
+    description: "The fastest path from install to your first contract and generated surface.",
+    section: "start",
+    order: 10,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/getting-started/installation",
+    title: "Installation",
+    description: "Install the CLI and core packages, then prepare a workspace for incremental adoption.",
+    section: "start",
+    order: 20,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/getting-started/hello-world",
+    title: "Hello world",
+    description: "Define a first operation, generate the surface, and verify the end-to-end loop.",
+    section: "start",
+    order: 30,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/getting-started/compatibility",
+    title: "Compatibility",
+    description: "Check the supported runtimes, package managers, and adoption assumptions before rollout.",
+    section: "start",
+    order: 40,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/getting-started/tools",
+    title: "Developer tools",
+    description: "Use the CLI, editors, and helper tooling that make the OSS workflow practical day to day.",
+    section: "start",
+    order: 50,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/getting-started/troubleshooting",
+    title: "Troubleshooting",
+    description: "Resolve the common installation, validation, and runtime mistakes you hit during first adoption.",
+    section: "start",
+    order: 60,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/specs",
+    title: "Contracts and specs",
+    description: "Understand the spec model that drives generated surfaces, validation, policy, and safe regeneration.",
+    section: "core-model",
+    order: 10,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/specs/capabilities",
+    title: "Capabilities",
+    description: "Model commands, queries, presentations, and events as explicit contract surfaces.",
+    section: "core-model",
+    order: 20,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/specs/dataviews",
+    title: "Data views",
+    description: "Define queryable, presentable views that stay aligned with the rest of the system.",
+    section: "core-model",
+    order: 30,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/specs/workflows",
+    title: "Workflows",
+    description: "Compose multi-step behavior from typed contracts, policies, and runtime orchestration.",
+    section: "core-model",
+    order: 40,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/specs/policy",
+    title: "Policy",
+    description: "Apply consistent governance, access rules, and risk controls across every surface.",
+    section: "core-model",
+    order: 50,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/specs/overlays",
+    title: "Overlays",
+    description: "Customize generated surfaces safely without forking the system or breaking regeneration.",
+    section: "core-model",
+    order: 60,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides/contract-types",
+    title: "Contract types",
+    description: "Choose the right contract surface for the behavior you want to make explicit.",
+    section: "core-model",
+    order: 70,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides",
+    title: "Guides",
+    description: "Follow concrete adoption paths for existing apps, generated docs, CI gating, and typed surfaces.",
+    section: "build",
+    order: 10,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides/nextjs-one-endpoint",
+    title: "Adopt one endpoint in Next.js",
+    description: "Start with one endpoint, one contract, and one generated surface in an existing Next.js app.",
+    section: "build",
+    order: 20,
+    navTitle: "Next.js endpoint",
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides/import-existing-codebases",
+    title: "Import an existing codebase",
+    description: "Stabilize a live codebase incrementally instead of rewriting it from scratch.",
+    section: "build",
+    order: 30,
+    navTitle: "Import existing code",
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides/spec-validation-and-typing",
+    title: "Validation and typing",
+    description: "Keep runtime validation and TypeScript types aligned from the same source definitions.",
+    section: "build",
+    order: 40,
+    navTitle: "Validation and typing",
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides/generate-docs-clients-schemas",
+    title: "Generate docs, clients, and schemas",
+    description: "Export stable docs and client-facing artifacts from the same contract layer.",
+    section: "build",
+    order: 50,
+    navTitle: "Generate docs and clients",
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "reference"
+  },
+  {
+    href: "/docs/guides/docs-generation-pipeline",
+    title: "Docs generation pipeline",
+    description: "Feed generated docs into the public docs site without breaking source-of-truth ownership.",
+    section: "build",
+    order: 60,
+    navTitle: "Docs pipeline",
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "reference"
+  },
+  {
+    href: "/docs/libraries",
+    title: "Libraries overview",
+    description: "Navigate the core libraries, runtimes, and system packages that make up the open foundation.",
+    section: "build",
+    order: 70,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/architecture",
+    title: "Architecture",
+    description: "See how the spec layer, runtimes, integrations, and multi-surface outputs fit together.",
+    section: "build",
+    order: 80,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/safety",
+    title: "Operate safely",
+    description: "Add auditability, migrations, policy controls, and trustworthy release behavior from the start.",
+    section: "operate",
+    order: 10,
+    navTitle: "Safety overview",
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/guides/ci-contract-diff-gating",
+    title: "CI diff gating",
+    description: "Use deterministic checks to block drift and risky changes before they reach production.",
+    section: "operate",
+    order: 20,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/safety/security-trust",
+    title: "Security and trust",
+    description: "Understand the trust model, artifact validation expectations, and operational boundaries.",
+    section: "operate",
+    order: 30,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/safety/auditing",
+    title: "Audit trails",
+    description: "Track changes, policy decisions, and operational actions with a clear evidence trail.",
+    section: "operate",
+    order: 40,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/safety/migrations",
+    title: "Migrations",
+    description: "Evolve schemas and data safely without abandoning the contract layer.",
+    section: "operate",
+    order: 50,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/safety/tenant-isolation",
+    title: "Tenant isolation",
+    description: "Keep tenant data, config, policies, and integrations separated at runtime.",
+    section: "operate",
+    order: 60,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/knowledge",
+    title: "Knowledge and context",
+    description: "Bind trusted knowledge sources to the system without losing governance or isolation.",
+    section: "operate",
+    order: 70,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/advanced/telemetry",
+    title: "Telemetry",
+    description: "Instrument surfaces, collect evidence, and keep observability aligned with the contract model.",
+    section: "operate",
+    order: 80,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/advanced/workflow-monitoring",
+    title: "Workflow monitoring",
+    description: "Observe multi-step execution with enough context to understand failures and regressions.",
+    section: "operate",
+    order: 90,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/ops/distributed-tracing",
+    title: "Distributed tracing",
+    description: "Trace contract execution across integrations, workflows, and generated surfaces.",
+    section: "operate",
+    order: 100,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations",
+    title: "Integrations overview",
+    description: "Understand the binding model for external services, providers, and tenant-owned connections.",
+    section: "integrations",
+    order: 10,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/spec-model",
+    title: "Integration spec model",
+    description: "Define what an integration provides before wiring it into an app or runtime.",
+    section: "integrations",
+    order: 20,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/openai",
+    title: "OpenAI integration",
+    description: "Connect OpenAI through typed capabilities, explicit provider config, and governed runtime usage.",
+    section: "integrations",
+    order: 30,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/mistral",
+    title: "Mistral integration",
+    description: "Use Mistral through the same provider contract model and runtime guardrails.",
+    section: "integrations",
+    order: 40,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/qdrant",
+    title: "Qdrant integration",
+    description: "Store and retrieve knowledge embeddings with explicit provider configuration and ownership.",
+    section: "integrations",
+    order: 50,
+    primaryNav: true,
+    audience: "operator",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/stripe",
+    title: "Stripe integration",
+    description: "Bind payments and billing behavior without smearing provider logic across the codebase.",
+    section: "integrations",
+    order: 60,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/twilio",
+    title: "Twilio integration",
+    description: "Handle messaging and telephony through typed transport boundaries and explicit configuration.",
+    section: "integrations",
+    order: 70,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/integrations/github",
+    title: "GitHub integration",
+    description: "Push execution context into GitHub workflows and automation surfaces without hidden glue.",
+    section: "integrations",
+    order: 80,
+    primaryNav: true,
+    audience: "oss",
+    ctaMode: "oss-next"
+  },
+  {
+    href: "/docs/reference",
+    title: "Contract reference",
+    description: "Browse the generated reference index for public contract surfaces, versions, and examples.",
+    section: "reference",
+    order: 10,
+    primaryNav: true,
+    audience: "reference",
+    ctaMode: "reference"
+  },
+  {
+    href: "/docs/examples",
+    title: "Examples",
+    description: "Explore runnable examples and use them as reference implementations for new systems.",
+    section: "reference",
+    order: 20,
+    primaryNav: true,
+    audience: "reference",
+    ctaMode: "reference"
+  },
+  {
+    href: "/docs/studio",
+    title: "Studio overview",
+    description: "See what Studio adds on top of OSS ContractSpec and when a team should adopt the operating layer.",
+    section: "studio",
+    order: 10,
+    primaryNav: true,
+    audience: "studio-bridge",
+    ctaMode: "studio-bridge"
+  },
+  {
+    href: "/docs/manifesto",
+    title: "Manifesto",
+    description: "Why ContractSpec is built as an open system, how incremental adoption works, and why Studio stays additive.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/intent/contract-first-api",
+    title: "Contract-first API",
+    description: "Use contracts as the durable source of truth for API behavior and generated surfaces.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/intent/spec-driven-development",
+    title: "Spec-driven development",
+    description: "See how explicit specs stabilize change across APIs, UI, data, and agent-facing surfaces.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/intent/deterministic-codegen",
+    title: "Deterministic regeneration",
+    description: "Understand safe regeneration, conflict boundaries, and why teams keep control of the output.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/intent/schema-validation-typescript",
+    title: "Schema validation and TypeScript",
+    description: "Keep schema, runtime validation, and TypeScript behavior aligned without duplicate work.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/intent/openapi-alternative",
+    title: "OpenAPI alternative",
+    description: "Compare a multi-surface contract system with API-only description tooling.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/intent/generate-client-from-schema",
+    title: "Generate client from schema",
+    description: "Generate client-facing artifacts from the same source that drives runtime behavior.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/comparison",
+    title: "Comparison overview",
+    description: "Compare ContractSpec with workflow engines, internal-tool builders, and enterprise orchestration products.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/comparison/workflow-engines",
+    title: "Workflow engines",
+    description: "Contrast a contract system with workflow-only orchestration approaches.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/comparison/internal-tool-builders",
+    title: "Internal-tool builders",
+    description: "Compare ContractSpec with builders that optimize for screens instead of durable system contracts.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/comparison/automation-platforms",
+    title: "Automation platforms",
+    description: "Compare automation-first tools with a system that owns explicit contracts and generated surfaces.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/comparison/windmill",
+    title: "Windmill comparison",
+    description: "Understand where Windmill fits and where ContractSpec solves a different class of system problem.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/comparison/enterprise-platforms",
+    title: "Enterprise orchestrators",
+    description: "Compare ContractSpec with enterprise platforms that centralize execution in a closed operating surface.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/ecosystem/templates",
+    title: "Templates",
+    description: "Use templates and starter systems as proof points and accelerators for OSS adoption.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/ecosystem/plugins",
+    title: "Plugins",
+    description: "Explore marketplace and editor integrations that support the OSS workflow.",
+    audience: "secondary"
+  },
+  {
+    href: "/docs/ecosystem/registry",
+    title: "Registry",
+    description: "Inspect registry and manifest concepts that help package reusable capability surfaces.",
+    audience: "secondary"
+  }
+];
+function getDocsPageByHref(href) {
+  return DOCS_PAGES.find((page) => page.href === href);
+}
+function getPrimaryDocsSections() {
+  return DOCS_PRIMARY_SECTIONS.map((section) => ({
+    ...section,
+    items: DOCS_PAGES.filter((page) => page.section === section.key && page.primaryNav).sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  }));
+}
+function getPrimaryDocsTraversal() {
+  return DOCS_PAGES.filter((page) => page.primaryNav).sort((a, b) => DOCS_PRIMARY_SECTIONS.findIndex((section) => section.key === a.section) - DOCS_PRIMARY_SECTIONS.findIndex((section) => section.key === b.section) || (a.order ?? 0) - (b.order ?? 0));
+}
+function getDocsNextPrevious(href) {
+  const traversal = getPrimaryDocsTraversal();
+  const index = traversal.findIndex((page) => page.href === href);
+  if (index < 0) {
+    return { previous: null, next: null };
+  }
+  return {
+    previous: traversal[index - 1] ?? null,
+    next: traversal[index + 1] ?? null
+  };
+}
+function getSecondaryDocsPages() {
+  return DOCS_PAGES.filter((page) => page.audience === "secondary");
+}
+function getDocsHomeSections() {
+  return getPrimaryDocsSections().map((section) => ({
+    ...section,
+    featured: section.items.slice(0, 3)
+  }));
+}
+
 // src/components/docs/DocsIndexPage.tsx
 import { CodeBlock } from "@contractspec/lib.design-system";
 import Link from "@contractspec/lib.ui-link";
-import { BookOpen, ChevronRight, Shield, Zap } from "lucide-react";
+import {
+  ArrowRight,
+  Boxes,
+  FileSearch,
+  ShieldCheck,
+  Waypoints
+} from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
+var proofPoints = [
+  {
+    title: "One system, many surfaces",
+    body: "Define explicit contracts once, then keep APIs, UI, data, events, and agent-facing surfaces aligned.",
+    icon: Boxes
+  },
+  {
+    title: "Incremental adoption",
+    body: "Start with one endpoint, one workflow, or one unsafe module. You do not need a rewrite to begin.",
+    icon: Waypoints
+  },
+  {
+    title: "Operator-grade controls",
+    body: "Carry policy, auditability, migrations, tracing, and integration boundaries forward with the same system model.",
+    icon: ShieldCheck
+  }
+];
 function DocsIndexPage() {
+  const sections = getDocsHomeSections();
+  const secondary = getSecondaryDocsPages().slice(0, 6);
   return /* @__PURE__ */ jsxs("div", {
     className: "space-y-12",
     children: [
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
+      /* @__PURE__ */ jsxs("section", {
+        className: "space-y-6",
         children: [
+          /* @__PURE__ */ jsx("p", {
+            className: "editorial-kicker",
+            children: "OSS documentation"
+          }),
           /* @__PURE__ */ jsx("h1", {
-            className: "text-4xl font-bold md:text-5xl",
-            children: "Documentation"
+            className: "editorial-title max-w-5xl",
+            children: "Build AI-native systems on explicit contracts, then add Studio when you want the operating layer."
           }),
           /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground max-w-2xl text-lg",
-            children: "Stabilize your AI-generated code. Define contracts once, generate consistent code across all surfaces, regenerate safely anytime."
+            className: "editorial-subtitle",
+            children: "These docs are optimized for OSS adopters first. Learn the contract model, generate and govern surfaces safely, wire integrations, and run the system in production without giving up ownership of your code."
+          }),
+          /* @__PURE__ */ jsxs("div", {
+            className: "flex flex-wrap gap-3",
+            children: [
+              /* @__PURE__ */ jsxs(Link, {
+                href: "/docs/getting-started/start-here",
+                className: "btn-primary text-sm",
+                children: [
+                  "Start with OSS ",
+                  /* @__PURE__ */ jsx(ArrowRight, {
+                    size: 16
+                  })
+                ]
+              }),
+              /* @__PURE__ */ jsx(Link, {
+                href: "/docs/studio",
+                className: "btn-ghost text-sm",
+                children: "See what Studio adds"
+              })
+            ]
           })
         ]
       }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "grid gap-6 md:grid-cols-3",
-        children: [
-          /* @__PURE__ */ jsx(Link, {
-            href: "/docs/getting-started/installation",
-            className: "card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50",
-            children: /* @__PURE__ */ jsxs("div", {
-              className: "flex items-start justify-between",
-              children: [
-                /* @__PURE__ */ jsxs("div", {
-                  children: [
-                    /* @__PURE__ */ jsx("h3", {
-                      className: "text-lg font-bold transition-colors group-hover:text-violet-400",
-                      children: "Get started"
-                    }),
-                    /* @__PURE__ */ jsx("p", {
-                      className: "text-muted-foreground mt-1 text-sm",
-                      children: "Install ContractSpec and define your first contract in minutes."
+      /* @__PURE__ */ jsx("section", {
+        className: "grid gap-5 md:grid-cols-3",
+        children: proofPoints.map((item) => {
+          const Icon = item.icon;
+          return /* @__PURE__ */ jsxs("article", {
+            className: "editorial-panel space-y-3",
+            children: [
+              /* @__PURE__ */ jsxs("div", {
+                className: "flex items-center gap-3",
+                children: [
+                  /* @__PURE__ */ jsx("div", {
+                    className: "rounded-full border border-border/80 bg-background/85 p-2",
+                    children: /* @__PURE__ */ jsx(Icon, {
+                      size: 18
                     })
-                  ]
-                }),
-                /* @__PURE__ */ jsx(Zap, {
-                  size: 20,
-                  className: "shrink-0 text-violet-400"
-                })
-              ]
-            })
+                  }),
+                  /* @__PURE__ */ jsx("h2", {
+                    className: "font-semibold text-xl",
+                    children: item.title
+                  })
+                ]
+              }),
+              /* @__PURE__ */ jsx("p", {
+                className: "editorial-copy text-sm",
+                children: item.body
+              })
+            ]
+          }, item.title);
+        })
+      }),
+      /* @__PURE__ */ jsxs("section", {
+        className: "editorial-panel space-y-5",
+        children: [
+          /* @__PURE__ */ jsxs("div", {
+            className: "space-y-2",
+            children: [
+              /* @__PURE__ */ jsx("p", {
+                className: "editorial-kicker",
+                children: "Quick start"
+              }),
+              /* @__PURE__ */ jsx("h2", {
+                className: "editorial-panel-title",
+                children: "Start with one contract"
+              }),
+              /* @__PURE__ */ jsx("p", {
+                className: "editorial-copy text-sm",
+                children: "Use the CLI and core libraries to define one explicit capability, generate the surface, and validate the contract boundary before you expand."
+              })
+            ]
           }),
-          /* @__PURE__ */ jsx(Link, {
-            href: "/docs/specs/capabilities",
-            className: "card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50",
-            children: /* @__PURE__ */ jsxs("div", {
-              className: "flex items-start justify-between",
-              children: [
-                /* @__PURE__ */ jsxs("div", {
-                  children: [
-                    /* @__PURE__ */ jsx("h3", {
-                      className: "text-lg font-bold transition-colors group-hover:text-violet-400",
-                      children: "Core contracts"
-                    }),
-                    /* @__PURE__ */ jsx("p", {
-                      className: "text-muted-foreground mt-1 text-sm",
-                      children: "Commands, queries, events, and presentations. The building blocks."
-                    })
-                  ]
-                }),
-                /* @__PURE__ */ jsx(BookOpen, {
-                  size: 20,
-                  className: "shrink-0 text-violet-400"
-                })
-              ]
-            })
+          /* @__PURE__ */ jsx(CodeBlock, {
+            language: "bash",
+            filename: "docs-quick-start",
+            code: `bun add -D contractspec
+bun add @contractspec/lib.contracts-spec @contractspec/lib.schema
+
+contractspec init
+contractspec create --type operation
+contractspec build src/contracts/mySpec.ts
+contractspec validate src/contracts/mySpec.ts`
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsxs("section", {
+        className: "space-y-5",
+        children: [
+          /* @__PURE__ */ jsxs("div", {
+            className: "space-y-2",
+            children: [
+              /* @__PURE__ */ jsx("p", {
+                className: "editorial-kicker",
+                children: "Primary path"
+              }),
+              /* @__PURE__ */ jsx("h2", {
+                className: "editorial-panel-title",
+                children: "Move through the system in the right order"
+              }),
+              /* @__PURE__ */ jsx("p", {
+                className: "editorial-copy text-sm",
+                children: "Start with onboarding, then learn the model, then build and operate with confidence. The primary docs path is intentionally shorter than the full route inventory."
+              })
+            ]
           }),
-          /* @__PURE__ */ jsx(Link, {
-            href: "/docs/safety/signing",
-            className: "card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50",
-            children: /* @__PURE__ */ jsxs("div", {
-              className: "flex items-start justify-between",
+          /* @__PURE__ */ jsx("div", {
+            className: "grid gap-5 lg:grid-cols-2",
+            children: sections.map((section) => /* @__PURE__ */ jsxs("article", {
+              className: "editorial-panel space-y-4",
               children: [
                 /* @__PURE__ */ jsxs("div", {
                   children: [
-                    /* @__PURE__ */ jsx("h3", {
-                      className: "text-lg font-bold transition-colors group-hover:text-violet-400",
-                      children: "Safe regeneration"
-                    }),
                     /* @__PURE__ */ jsx("p", {
-                      className: "text-muted-foreground mt-1 text-sm",
-                      children: "Golden tests, migrations, signing, and audit trails."
-                    })
-                  ]
-                }),
-                /* @__PURE__ */ jsx(Shield, {
-                  size: 20,
-                  className: "shrink-0 text-violet-400"
-                })
-              ]
-            })
-          }),
-          /* @__PURE__ */ jsx(Link, {
-            href: "/docs/studio",
-            className: "card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50",
-            children: /* @__PURE__ */ jsxs("div", {
-              className: "flex items-start justify-between",
-              children: [
-                /* @__PURE__ */ jsxs("div", {
-                  children: [
+                      className: "editorial-kicker",
+                      children: section.title
+                    }),
                     /* @__PURE__ */ jsx("h3", {
-                      className: "text-lg font-bold transition-colors group-hover:text-violet-400",
-                      children: "Studio"
+                      className: "mt-2 font-serif text-3xl tracking-[-0.03em]",
+                      children: section.title
                     }),
                     /* @__PURE__ */ jsx("p", {
-                      className: "text-muted-foreground mt-1 text-sm",
-                      children: "AI-powered product decision engine for spec-first teams."
+                      className: "mt-3 text-muted-foreground text-sm leading-7",
+                      children: section.description
                     })
                   ]
                 }),
-                /* @__PURE__ */ jsx(Zap, {
-                  size: 20,
-                  className: "shrink-0 text-violet-400"
+                /* @__PURE__ */ jsx("div", {
+                  className: "space-y-3",
+                  children: section.featured.map((page) => /* @__PURE__ */ jsxs(Link, {
+                    href: page.href,
+                    className: "flex items-start justify-between gap-4 rounded-[22px] border border-border/70 bg-background/70 p-4 transition-colors hover:border-[color:rgb(162_79_42_/_0.45)]",
+                    children: [
+                      /* @__PURE__ */ jsxs("div", {
+                        children: [
+                          /* @__PURE__ */ jsx("h4", {
+                            className: "font-semibold text-base",
+                            children: page.title
+                          }),
+                          /* @__PURE__ */ jsx("p", {
+                            className: "mt-1 text-muted-foreground text-sm leading-6",
+                            children: page.description
+                          })
+                        ]
+                      }),
+                      /* @__PURE__ */ jsx(ArrowRight, {
+                        className: "mt-1 shrink-0",
+                        size: 16
+                      })
+                    ]
+                  }, page.href))
                 })
               ]
-            })
+            }, section.key))
           })
         ]
       }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
+      /* @__PURE__ */ jsxs("section", {
+        className: "grid gap-5 lg:grid-cols-[1.2fr_0.8fr]",
         children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Quick start"
-          }),
-          /* @__PURE__ */ jsxs("div", {
-            className: "card-subtle space-y-4 p-6",
+          /* @__PURE__ */ jsxs("article", {
+            className: "editorial-panel space-y-4",
             children: [
-              /* @__PURE__ */ jsx("p", {
-                className: "text-muted-foreground",
-                children: "Add ContractSpec to your project and define your first contract:"
-              }),
-              /* @__PURE__ */ jsx(CodeBlock, {
-                language: "bash",
-                filename: "docs-quick-start",
-                code: `# Install the CLI and core libraries
-bun add -D contractspec
-bun add @contractspec/lib.contracts-spec @contractspec/lib.schema
-
-# Create your first contract
-bun contractspec create --type operation
-
-# Generate implementation
-bun contractspec build src/contracts/mySpec.ts`
+              /* @__PURE__ */ jsxs("div", {
+                className: "space-y-2",
+                children: [
+                  /* @__PURE__ */ jsx("p", {
+                    className: "editorial-kicker",
+                    children: "Reference and evidence"
+                  }),
+                  /* @__PURE__ */ jsx("h2", {
+                    className: "editorial-panel-title",
+                    children: "Use generated docs and examples as proof, not just narrative copy"
+                  }),
+                  /* @__PURE__ */ jsx("p", {
+                    className: "editorial-copy text-sm",
+                    children: "The reference index and example catalog stay close to the repo truth. Use them when you need exact public surfaces, not just the explanatory layer."
+                  })
+                ]
               }),
               /* @__PURE__ */ jsxs("div", {
-                className: "flex flex-wrap gap-2",
+                className: "grid gap-4 md:grid-cols-2",
                 children: [
                   /* @__PURE__ */ jsxs(Link, {
-                    href: "/docs/getting-started/installation",
-                    className: "btn-primary text-sm",
+                    href: "/docs/reference",
+                    className: "docs-footer-link",
                     children: [
-                      "Installation guide ",
-                      /* @__PURE__ */ jsx(ChevronRight, {
-                        size: 16
+                      /* @__PURE__ */ jsxs("div", {
+                        className: "flex items-center gap-2 text-muted-foreground text-sm",
+                        children: [
+                          /* @__PURE__ */ jsx(FileSearch, {
+                            size: 16
+                          }),
+                          /* @__PURE__ */ jsx("span", {
+                            children: "Reference index"
+                          })
+                        ]
+                      }),
+                      /* @__PURE__ */ jsx("p", {
+                        className: "text-muted-foreground text-sm",
+                        children: "Search generated contract docs, versions, tags, and visibility metadata."
                       })
                     ]
                   }),
-                  /* @__PURE__ */ jsx(Link, {
-                    href: "/docs/getting-started/hello-world",
-                    className: "btn-ghost text-sm",
-                    children: "First contract tutorial"
+                  /* @__PURE__ */ jsxs(Link, {
+                    href: "/docs/examples",
+                    className: "docs-footer-link",
+                    children: [
+                      /* @__PURE__ */ jsxs("div", {
+                        className: "flex items-center gap-2 text-muted-foreground text-sm",
+                        children: [
+                          /* @__PURE__ */ jsx(Boxes, {
+                            size: 16
+                          }),
+                          /* @__PURE__ */ jsx("span", {
+                            children: "Examples"
+                          })
+                        ]
+                      }),
+                      /* @__PURE__ */ jsx("p", {
+                        className: "text-muted-foreground text-sm",
+                        children: "Browse runnable examples and follow the reference routes back to their source artifacts."
+                      })
+                    ]
                   })
                 ]
               })
             ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Browse all documentation"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "Use the sidebar or choose a topic to explore spec-first development."
           }),
-          /* @__PURE__ */ jsx("div", {
-            className: "mt-6 grid gap-4 md:grid-cols-2",
+          /* @__PURE__ */ jsxs("article", {
+            className: "editorial-panel space-y-4",
             children: [
-              {
-                title: "Getting Started",
-                description: "Installation, first contract, and CLI usage",
-                href: "/docs/getting-started/installation"
-              },
-              {
-                title: "Guides",
-                description: "Runnable adoption scenarios with examples",
-                href: "/docs/guides"
-              },
-              {
-                title: "Intent Pages",
-                description: "SEO-optimized pages for specific developer needs",
-                href: "/docs/intent"
-              },
-              {
-                title: "Ecosystem",
-                description: "Cursor marketplace plugins, templates, manifest, and integrations",
-                href: "/docs/ecosystem/plugins"
-              },
-              {
-                title: "Core Contracts",
-                description: "Commands, queries, events, presentations, workflows",
-                href: "/docs/specs/capabilities"
-              },
-              {
-                title: "Safe Regeneration",
-                description: "Signing, migrations, golden tests, compliance",
-                href: "/docs/safety/signing"
-              },
-              {
-                title: "Multi-Surface Output",
-                description: "REST, GraphQL, Prisma, MCP tools, React",
-                href: "/docs/advanced/renderers"
-              },
-              {
-                title: "Libraries",
-                description: "Core runtime libraries and utilities",
-                href: "/docs/libraries"
-              },
-              {
-                title: "AI Governance",
-                description: "Agents, contract enforcement, approval workflows",
-                href: "/docs/libraries/ai-agent"
-              },
-              {
-                title: "Architecture",
-                description: "Multi-tenancy, integrations, knowledge sources",
-                href: "/docs/architecture"
-              },
-              {
-                title: "Manifesto",
-                description: "Our philosophy: compiler not prison",
-                href: "/docs/manifesto"
-              }
-            ].map((topic, i) => /* @__PURE__ */ jsxs(Link, {
-              href: topic.href,
-              className: "card-subtle group p-4 transition-colors hover:border-violet-500/50",
-              children: [
-                /* @__PURE__ */ jsx("h3", {
-                  className: "font-bold transition-colors group-hover:text-violet-400",
-                  children: topic.title
-                }),
-                /* @__PURE__ */ jsx("p", {
-                  className: "text-muted-foreground mt-1 text-sm",
-                  children: topic.description
-                })
-              ]
-            }, i))
+              /* @__PURE__ */ jsxs("div", {
+                className: "space-y-2",
+                children: [
+                  /* @__PURE__ */ jsx("p", {
+                    className: "editorial-kicker",
+                    children: "Secondary reading"
+                  }),
+                  /* @__PURE__ */ jsx("h2", {
+                    className: "editorial-panel-title",
+                    children: "Why ContractSpec"
+                  }),
+                  /* @__PURE__ */ jsx("p", {
+                    className: "editorial-copy text-sm",
+                    children: "Positioning, comparisons, and philosophy remain available, but they no longer define the main docs path."
+                  })
+                ]
+              }),
+              /* @__PURE__ */ jsx("div", {
+                className: "flex flex-wrap gap-2",
+                children: secondary.map((page) => /* @__PURE__ */ jsx(Link, {
+                  href: page.href,
+                  className: "docs-chip-link",
+                  children: page.title
+                }, page.href))
+              })
+            ]
           })
         ]
       })