@contractspec/bundle.library 3.7.5 → 3.7.7

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

@@ -1,397 +1,51 @@
 // @bun
-// src/components/docs/specs/SpecsOverviewPage.tsx
+// src/components/docs/specs/SpecsCapabilitiesPage.tsx
 import Link from "@contractspec/lib.ui-link";
 import { ChevronRight } from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
-function SpecsOverviewPage() {
+function SpecsCapabilitiesPage() {
   return /* @__PURE__ */ jsxs("div", {
     className: "space-y-8",
     children: [
       /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h1", {
-            className: "text-4xl font-bold",
-            children: "Specifications Overview"
-          }),
-          /* @__PURE__ */ jsxs("p", {
-            className: "text-muted-foreground",
-            children: [
-              "ContractSpec is built on a ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "spec-first"
-              }),
-              " philosophy. You define declarative TypeScript specifications that describe what your application can do. Runtime adapters automatically serve these specs as type-safe API endpoints (REST, GraphQL, MCP), enforce policies, and validate inputs/outputs\u2014no code generation required."
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Why spec-first matters"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "Traditional development requires writing and maintaining separate code for APIs, databases, UI components, validation logic, and access control. This approach leads to:"
-          }),
-          /* @__PURE__ */ jsxs("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
-            children: [
-              /* @__PURE__ */ jsx("li", {
-                children: "Duplication across front-end and back-end"
-              }),
-              /* @__PURE__ */ jsx("li", {
-                children: "Type mismatches and runtime errors"
-              }),
-              /* @__PURE__ */ jsx("li", {
-                children: "Security vulnerabilities from inconsistent policy enforcement"
-              }),
-              /* @__PURE__ */ jsx("li", {
-                children: "High maintenance burden when requirements change"
-              })
-            ]
-          }),
-          /* @__PURE__ */ jsxs("p", {
-            className: "text-muted-foreground",
-            children: [
-              "With ContractSpec, you define your application's operations (Commands/Queries), workflows, and policies in pure TypeScript. Runtime adapters ensure consistency, type safety, and policy enforcement across your entire stack\u2014the spec ",
-              /* @__PURE__ */ jsx("em", {
-                children: "is"
-              }),
-              " the implementation."
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Specification types"
-          }),
-          /* @__PURE__ */ jsx("div", {
-            className: "border-border/50 overflow-x-auto rounded-lg border",
-            children: /* @__PURE__ */ jsxs("table", {
-              className: "w-full text-left text-sm",
-              children: [
-                /* @__PURE__ */ jsx("thead", {
-                  className: "bg-card/50",
-                  children: /* @__PURE__ */ jsxs("tr", {
-                    className: "border-border/50 border-b",
-                    children: [
-                      /* @__PURE__ */ jsx("th", {
-                        className: "px-4 py-3 font-semibold",
-                        children: "Spec Type"
-                      }),
-                      /* @__PURE__ */ jsx("th", {
-                        className: "px-4 py-3 font-semibold",
-                        children: "Purpose"
-                      }),
-                      /* @__PURE__ */ jsx("th", {
-                        className: "px-4 py-3 font-semibold",
-                        children: "Generates"
-                      })
-                    ]
-                  })
-                }),
-                /* @__PURE__ */ jsxs("tbody", {
-                  className: "divide-border/50 divide-y",
-                  children: [
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx(Link, {
-                            href: "/docs/specs/capabilities",
-                            className: "text-violet-400 hover:text-violet-300",
-                            children: /* @__PURE__ */ jsx("strong", {
-                              children: "CapabilitySpec"
-                            })
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Defines what your application can do: operations (Commands/Queries), their inputs, outputs, policies, and side effects."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Runtime-served REST/GraphQL/MCP endpoints, Zod validation, policy enforcement"
-                        })
-                      ]
-                    }),
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx("strong", {
-                            children: "DataViewSpec"
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Describes how data should be queried, filtered, sorted, and presented to users."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Database queries, list/detail views, search interfaces"
-                        })
-                      ]
-                    }),
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx(Link, {
-                            href: "/docs/specs/workflows",
-                            className: "text-violet-400 hover:text-violet-300",
-                            children: /* @__PURE__ */ jsx("strong", {
-                              children: "WorkflowSpec"
-                            })
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Orchestrates multi-step processes with retries, compensation, and monitoring."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Workflow engine, state machines, retry logic, observability hooks"
-                        })
-                      ]
-                    }),
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx("strong", {
-                            children: "PolicySpec"
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Defines who can do what, when, and under what conditions. Supports ABAC and PII rules."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Policy decision points, access control middleware, audit logs"
-                        })
-                      ]
-                    }),
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx("strong", {
-                            children: "OverlaySpec"
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Allows safe, signed customization of UI layouts and field visibility by tenants or users."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Personalized UI components, layout variations, conditional rendering"
-                        })
-                      ]
-                    }),
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx("strong", {
-                            children: "TelemetrySpec"
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Specifies what metrics, logs, and traces to collect for observability."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Instrumentation code, dashboards, alerting rules"
-                        })
-                      ]
-                    }),
-                    /* @__PURE__ */ jsxs("tr", {
-                      children: [
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: /* @__PURE__ */ jsx(Link, {
-                            href: "/docs/safety/migrations",
-                            className: "text-violet-400 hover:text-violet-300",
-                            children: /* @__PURE__ */ jsx("strong", {
-                              children: "MigrationSpec"
-                            })
-                          })
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Manages incremental, reversible schema and data migrations."
-                        }),
-                        /* @__PURE__ */ jsx("td", {
-                          className: "px-4 py-3 align-top",
-                          children: "Migration scripts, rollback procedures, version tracking"
-                        })
-                      ]
-                    })
-                  ]
-                })
-              ]
-            })
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "How specs work together"
-          }),
-          /* @__PURE__ */ jsxs("p", {
-            className: "text-muted-foreground",
-            children: [
-              "Specs compose naturally. A ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "WorkflowSpec"
-              }),
-              " can invoke multiple ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "CapabilitySpecs"
-              }),
-              ". A",
-              " ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "DataViewSpec"
-              }),
-              " respects ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "PolicySpecs"
-              }),
-              " to filter sensitive fields. An ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "OverlaySpec"
-              }),
-              " can hide or rearrange UI elements generated from a ",
-              /* @__PURE__ */ jsx("strong", {
-                children: "CapabilitySpec"
-              }),
-              ", but only within the bounds allowed by the underlying policy."
-            ]
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "This composability means you can build complex applications from simple, reusable building blocks\u2014all while maintaining type safety and policy enforcement."
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Next steps"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "Explore each specification type in detail using the links in the table above, or continue with the core concepts:"
-          }),
-          /* @__PURE__ */ jsxs("div", {
-            className: "flex flex-wrap gap-4 pt-4",
-            children: [
-              /* @__PURE__ */ jsxs(Link, {
-                href: "/docs/specs/capabilities",
-                className: "btn-primary",
-                children: [
-                  "Capabilities ",
-                  /* @__PURE__ */ jsx(ChevronRight, {
-                    size: 16,
-                    className: "inline"
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs(Link, {
-                href: "/docs/specs/workflows",
-                className: "btn-ghost",
-                children: [
-                  "Workflows ",
-                  /* @__PURE__ */ jsx(ChevronRight, {
-                    size: 16,
-                    className: "inline"
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs(Link, {
-                href: "/docs/safety",
-                className: "btn-ghost",
-                children: [
-                  "Safety Features ",
-                  /* @__PURE__ */ jsx(ChevronRight, {
-                    size: 16,
-                    className: "inline"
-                  })
-                ]
-              })
-            ]
-          })
-        ]
-      })
-    ]
-  });
-}
-
-// src/components/docs/specs/SpecsCapabilitiesPage.tsx
-import Link2 from "@contractspec/lib.ui-link";
-import { ChevronRight as ChevronRight2 } from "lucide-react";
-import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
-function SpecsCapabilitiesPage() {
-  return /* @__PURE__ */ jsxs2("div", {
-    className: "space-y-8",
-    children: [
-      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-2",
         children: [
-          /* @__PURE__ */ jsx2("h1", {
-            className: "text-4xl font-bold",
+          /* @__PURE__ */ jsx("h1", {
+            className: "font-bold text-4xl",
             children: "Capabilities"
           }),
-          /* @__PURE__ */ jsx2("p", {
-            className: "text-muted-foreground text-lg",
+          /* @__PURE__ */ jsx("p", {
+            className: "text-lg text-muted-foreground",
             children: "Capabilities are the core building block of ContractSpec. They define what your app can do."
           })
         ]
       }),
-      /* @__PURE__ */ jsxs2("div", {
+      /* @__PURE__ */ jsxs("div", {
         className: "space-y-6",
         children: [
-          /* @__PURE__ */ jsxs2("div", {
+          /* @__PURE__ */ jsxs("div", {
             className: "space-y-3",
             children: [
-              /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+              /* @__PURE__ */ jsx("h2", {
+                className: "font-bold text-2xl",
                 children: "Overview"
               }),
-              /* @__PURE__ */ jsx2("p", {
+              /* @__PURE__ */ jsx("p", {
                 className: "text-muted-foreground",
                 children: "A ContractSpec (or Capability) is a typed, declarative description of an operation. It defines the operation's name, version, inputs, outputs, policies, and side effects. Runtime adapters automatically serve these as REST/GraphQL/MCP endpoints with full validation and policy enforcement."
               })
             ]
           }),
-          /* @__PURE__ */ jsxs2("div", {
+          /* @__PURE__ */ jsxs("div", {
             className: "space-y-3",
             children: [
-              /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+              /* @__PURE__ */ jsx("h2", {
+                className: "font-bold text-2xl",
                 children: "Defining a Command (Write)"
               }),
-              /* @__PURE__ */ jsx2("div", {
-                className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
-                children: /* @__PURE__ */ jsx2("pre", {
+              /* @__PURE__ */ jsx("div", {
+                className: "overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",
+                children: /* @__PURE__ */ jsx("pre", {
                   children: `import { defineCommand } from '@contractspec/lib.contracts-spec';
 import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 
@@ -435,80 +89,80 @@ export const TransferFunds = defineCommand({
               })
             ]
           }),
-          /* @__PURE__ */ jsxs2("div", {
+          /* @__PURE__ */ jsxs("div", {
             className: "space-y-3",
             children: [
-              /* @__PURE__ */ jsx2("h2", {
-                className: "text-2xl font-bold",
+              /* @__PURE__ */ jsx("h2", {
+                className: "font-bold text-2xl",
                 children: "Schema Types"
               }),
-              /* @__PURE__ */ jsxs2("p", {
+              /* @__PURE__ */ jsxs("p", {
                 className: "text-muted-foreground",
                 children: [
                   "ContractSpec uses ",
-                  /* @__PURE__ */ jsx2("code", {
+                  /* @__PURE__ */ jsx("code", {
                     children: "@contractspec/lib.schema"
                   }),
                   " for I/O definitions. This provides Zod validation, GraphQL types, and JSON Schema from a single source."
                 ]
               }),
-              /* @__PURE__ */ jsxs2("ul", {
-                className: "text-muted-foreground space-y-2",
+              /* @__PURE__ */ jsxs("ul", {
+                className: "space-y-2 text-muted-foreground",
                 children: [
-                  /* @__PURE__ */ jsxs2("li", {
+                  /* @__PURE__ */ jsxs("li", {
                     children: [
                       "\u2022",
                       " ",
-                      /* @__PURE__ */ jsx2("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                      /* @__PURE__ */ jsx("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "ScalarTypeEnum.NonEmptyString()"
                       }),
                       " ",
                       "- Non-empty text"
                     ]
                   }),
-                  /* @__PURE__ */ jsxs2("li", {
+                  /* @__PURE__ */ jsxs("li", {
                     children: [
                       "\u2022",
                       " ",
-                      /* @__PURE__ */ jsx2("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                      /* @__PURE__ */ jsx("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "ScalarTypeEnum.PositiveNumber()"
                       }),
                       " ",
                       "- Positive numbers"
                     ]
                   }),
-                  /* @__PURE__ */ jsxs2("li", {
+                  /* @__PURE__ */ jsxs("li", {
                     children: [
                       "\u2022",
                       " ",
-                      /* @__PURE__ */ jsx2("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                      /* @__PURE__ */ jsx("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "ScalarTypeEnum.DateTime()"
                       }),
                       " ",
                       "- ISO 8601 timestamps"
                     ]
                   }),
-                  /* @__PURE__ */ jsxs2("li", {
+                  /* @__PURE__ */ jsxs("li", {
                     children: [
                       "\u2022",
                       " ",
-                      /* @__PURE__ */ jsx2("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                      /* @__PURE__ */ jsx("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "ScalarTypeEnum.Email()"
                       }),
                       " ",
                       "- Valid email addresses"
                     ]
                   }),
-                  /* @__PURE__ */ jsxs2("li", {
+                  /* @__PURE__ */ jsxs("li", {
                     children: [
                       "\u2022",
                       " ",
-                      /* @__PURE__ */ jsx2("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                      /* @__PURE__ */ jsx("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "defineEnum(...)"
                       }),
                       " ",
@@ -519,14 +173,14 @@ export const TransferFunds = defineCommand({
               })
             ]
           }),
-          /* @__PURE__ */ jsx2("div", {
+          /* @__PURE__ */ jsx("div", {
             className: "flex items-center gap-4 pt-4",
-            children: /* @__PURE__ */ jsxs2(Link2, {
+            children: /* @__PURE__ */ jsxs(Link, {
               href: "/docs/specs/dataviews",
               className: "btn-primary",
               children: [
                 "Next: DataViews ",
-                /* @__PURE__ */ jsx2(ChevronRight2, {
+                /* @__PURE__ */ jsx(ChevronRight, {
                   size: 16
                 })
               ]
@@ -539,25 +193,25 @@ export const TransferFunds = defineCommand({
 }
 
 // src/components/docs/specs/SpecsDataViewsPage.tsx
-import Link3 from "@contractspec/lib.ui-link";
-import { ChevronRight as ChevronRight3 } from "lucide-react";
-import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+import Link2 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight2 } from "lucide-react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 function SpecsDataViewsPage() {
-  return /* @__PURE__ */ jsxs3("div", {
+  return /* @__PURE__ */ jsxs2("div", {
     className: "space-y-8",
     children: [
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx3("h1", {
-            className: "text-4xl font-bold",
+          /* @__PURE__ */ jsx2("h1", {
+            className: "font-bold text-4xl",
             children: "DataViews"
           }),
-          /* @__PURE__ */ jsxs3("p", {
+          /* @__PURE__ */ jsxs2("p", {
             className: "text-muted-foreground",
             children: [
               "A ",
-              /* @__PURE__ */ jsx3("strong", {
+              /* @__PURE__ */ jsx2("strong", {
                 children: "DataViewSpec"
               }),
               " describes how data should be queried, filtered, sorted, and presented to users. Runtime adapters execute optimized database queries and serve list views, detail views, and search interfaces while respecting policy constraints."
@@ -565,71 +219,71 @@ function SpecsDataViewsPage() {
           })
         ]
       }),
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx3("h2", {
-            className: "text-2xl font-bold",
+          /* @__PURE__ */ jsx2("h2", {
+            className: "font-bold text-2xl",
             children: "Core concepts"
           }),
-          /* @__PURE__ */ jsxs3("div", {
+          /* @__PURE__ */ jsxs2("div", {
             className: "space-y-3",
             children: [
-              /* @__PURE__ */ jsxs3("div", {
+              /* @__PURE__ */ jsxs2("div", {
                 children: [
-                  /* @__PURE__ */ jsx3("h3", {
-                    className: "text-lg font-semibold",
+                  /* @__PURE__ */ jsx2("h3", {
+                    className: "font-semibold text-lg",
                     children: "Data sources"
                   }),
-                  /* @__PURE__ */ jsx3("p", {
+                  /* @__PURE__ */ jsx2("p", {
                     className: "text-muted-foreground",
                     children: "A DataView connects to one or more data sources\u2014databases, APIs, or other capabilities. You specify the source and the fields you want to expose."
                   })
                 ]
               }),
-              /* @__PURE__ */ jsxs3("div", {
+              /* @__PURE__ */ jsxs2("div", {
                 children: [
-                  /* @__PURE__ */ jsx3("h3", {
-                    className: "text-lg font-semibold",
+                  /* @__PURE__ */ jsx2("h3", {
+                    className: "font-semibold text-lg",
                     children: "Filtering"
                   }),
-                  /* @__PURE__ */ jsx3("p", {
+                  /* @__PURE__ */ jsx2("p", {
                     className: "text-muted-foreground",
                     children: `Define filters that users can apply to narrow down results. Filters can be simple (e.g., "status equals 'active'") or complex (e.g., "created within the last 30 days AND assigned to current user").`
                   })
                 ]
               }),
-              /* @__PURE__ */ jsxs3("div", {
+              /* @__PURE__ */ jsxs2("div", {
                 children: [
-                  /* @__PURE__ */ jsx3("h3", {
-                    className: "text-lg font-semibold",
+                  /* @__PURE__ */ jsx2("h3", {
+                    className: "font-semibold text-lg",
                     children: "Sorting"
                   }),
-                  /* @__PURE__ */ jsx3("p", {
+                  /* @__PURE__ */ jsx2("p", {
                     className: "text-muted-foreground",
                     children: "Specify which fields can be sorted and the default sort order. ContractSpec generates efficient database queries with proper indexes."
                   })
                 ]
               }),
-              /* @__PURE__ */ jsxs3("div", {
+              /* @__PURE__ */ jsxs2("div", {
                 children: [
-                  /* @__PURE__ */ jsx3("h3", {
-                    className: "text-lg font-semibold",
+                  /* @__PURE__ */ jsx2("h3", {
+                    className: "font-semibold text-lg",
                     children: "Pagination"
                   }),
-                  /* @__PURE__ */ jsx3("p", {
+                  /* @__PURE__ */ jsx2("p", {
                     className: "text-muted-foreground",
                     children: "DataViews automatically support pagination to handle large datasets. You can configure page size limits and cursor-based or offset-based pagination."
                   })
                 ]
               }),
-              /* @__PURE__ */ jsxs3("div", {
+              /* @__PURE__ */ jsxs2("div", {
                 children: [
-                  /* @__PURE__ */ jsx3("h3", {
-                    className: "text-lg font-semibold",
+                  /* @__PURE__ */ jsx2("h3", {
+                    className: "font-semibold text-lg",
                     children: "Aggregations"
                   }),
-                  /* @__PURE__ */ jsx3("p", {
+                  /* @__PURE__ */ jsx2("p", {
                     className: "text-muted-foreground",
                     children: "Compute aggregates like counts, sums, averages, and group-by operations. These are useful for dashboards and summary views."
                   })
@@ -639,20 +293,20 @@ function SpecsDataViewsPage() {
           })
         ]
       }),
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx3("h2", {
-            className: "text-2xl font-bold",
+          /* @__PURE__ */ jsx2("h2", {
+            className: "font-bold text-2xl",
             children: "Example DataViewSpec"
           }),
-          /* @__PURE__ */ jsx3("p", {
+          /* @__PURE__ */ jsx2("p", {
             className: "text-muted-foreground",
             children: "Here's a DataView for listing orders in TypeScript:"
           }),
-          /* @__PURE__ */ jsx3("div", {
-            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
-            children: /* @__PURE__ */ jsx3("pre", {
+          /* @__PURE__ */ jsx2("div", {
+            className: "overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",
+            children: /* @__PURE__ */ jsx2("pre", {
               children: `import { defineDataView } from '@contractspec/lib.contracts-spec';
 import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 
@@ -698,19 +352,19 @@ export const OrderList = defineDataView({
           })
         ]
       }),
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx3("h2", {
-            className: "text-2xl font-bold",
+          /* @__PURE__ */ jsx2("h2", {
+            className: "font-bold text-2xl",
             children: "Policy integration"
           }),
-          /* @__PURE__ */ jsxs3("p", {
+          /* @__PURE__ */ jsxs2("p", {
             className: "text-muted-foreground",
             children: [
               "DataViews automatically enforce",
               " ",
-              /* @__PURE__ */ jsx3(Link3, {
+              /* @__PURE__ */ jsx2(Link2, {
                 href: "/docs/specs/policy",
                 className: "text-violet-400 hover:text-violet-300",
                 children: "PolicySpecs"
@@ -718,61 +372,61 @@ export const OrderList = defineDataView({
               ". If a user doesn't have permission to see certain fields, those fields are automatically filtered out or redacted. If a user can only see their own data, the query is automatically scoped."
             ]
           }),
-          /* @__PURE__ */ jsx3("p", {
+          /* @__PURE__ */ jsx2("p", {
             className: "text-muted-foreground",
             children: "This means you define the data view once, and it works correctly for all users based on their permissions\u2014no need to write separate queries for different roles."
           })
         ]
       }),
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx3("h2", {
-            className: "text-2xl font-bold",
+          /* @__PURE__ */ jsx2("h2", {
+            className: "font-bold text-2xl",
             children: "Served outputs"
           }),
-          /* @__PURE__ */ jsx3("p", {
+          /* @__PURE__ */ jsx2("p", {
             className: "text-muted-foreground",
             children: "From a DataViewSpec, ContractSpec serves:"
           }),
-          /* @__PURE__ */ jsxs3("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+          /* @__PURE__ */ jsxs2("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
-              /* @__PURE__ */ jsxs3("li", {
+              /* @__PURE__ */ jsxs2("li", {
                 children: [
-                  /* @__PURE__ */ jsx3("strong", {
+                  /* @__PURE__ */ jsx2("strong", {
                     children: "Database queries"
                   }),
                   " \u2013 Optimized SQL or NoSQL queries executed at runtime"
                 ]
               }),
-              /* @__PURE__ */ jsxs3("li", {
+              /* @__PURE__ */ jsxs2("li", {
                 children: [
-                  /* @__PURE__ */ jsx3("strong", {
+                  /* @__PURE__ */ jsx2("strong", {
                     children: "API endpoints"
                   }),
                   " \u2013 RESTful or GraphQL endpoints for fetching data"
                 ]
               }),
-              /* @__PURE__ */ jsxs3("li", {
+              /* @__PURE__ */ jsxs2("li", {
                 children: [
-                  /* @__PURE__ */ jsx3("strong", {
+                  /* @__PURE__ */ jsx2("strong", {
                     children: "UI components"
                   }),
                   " \u2013 List views, tables, cards, and detail views"
                 ]
               }),
-              /* @__PURE__ */ jsxs3("li", {
+              /* @__PURE__ */ jsxs2("li", {
                 children: [
-                  /* @__PURE__ */ jsx3("strong", {
+                  /* @__PURE__ */ jsx2("strong", {
                     children: "Search interfaces"
                   }),
                   " \u2013 Full-text search with autocomplete"
                 ]
               }),
-              /* @__PURE__ */ jsxs3("li", {
+              /* @__PURE__ */ jsxs2("li", {
                 children: [
-                  /* @__PURE__ */ jsx3("strong", {
+                  /* @__PURE__ */ jsx2("strong", {
                     children: "Export functions"
                   }),
                   " \u2013 CSV, JSON, or Excel exports"
@@ -782,49 +436,49 @@ export const OrderList = defineDataView({
           })
         ]
       }),
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx3("h2", {
-            className: "text-2xl font-bold",
+          /* @__PURE__ */ jsx2("h2", {
+            className: "font-bold text-2xl",
             children: "Best practices"
           }),
-          /* @__PURE__ */ jsxs3("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+          /* @__PURE__ */ jsxs2("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
-              /* @__PURE__ */ jsx3("li", {
+              /* @__PURE__ */ jsx2("li", {
                 children: "Only expose fields that users actually need\u2014this improves performance and security."
               }),
-              /* @__PURE__ */ jsx3("li", {
+              /* @__PURE__ */ jsx2("li", {
                 children: "Use appropriate indexes for sortable and filterable fields."
               }),
-              /* @__PURE__ */ jsx3("li", {
+              /* @__PURE__ */ jsx2("li", {
                 children: "Set reasonable pagination limits to prevent performance issues."
               }),
-              /* @__PURE__ */ jsx3("li", {
+              /* @__PURE__ */ jsx2("li", {
                 children: "Use aggregations sparingly\u2014they can be expensive on large datasets."
               }),
-              /* @__PURE__ */ jsx3("li", {
+              /* @__PURE__ */ jsx2("li", {
                 children: "Test DataViews with realistic data volumes to ensure they perform well."
               })
             ]
           })
         ]
       }),
-      /* @__PURE__ */ jsxs3("div", {
+      /* @__PURE__ */ jsxs2("div", {
         className: "flex items-center gap-4 pt-4",
         children: [
-          /* @__PURE__ */ jsx3(Link3, {
+          /* @__PURE__ */ jsx2(Link2, {
             href: "/docs/specs/capabilities",
             className: "btn-ghost",
             children: "Previous: Capabilities"
           }),
-          /* @__PURE__ */ jsxs3(Link3, {
+          /* @__PURE__ */ jsxs2(Link2, {
             href: "/docs/specs/workflows",
             className: "btn-primary",
             children: [
               "Next: Workflows ",
-              /* @__PURE__ */ jsx3(ChevronRight3, {
+              /* @__PURE__ */ jsx2(ChevronRight2, {
                 size: 16
               })
             ]
@@ -835,360 +489,589 @@ export const OrderList = defineDataView({
   });
 }
 
-// src/components/docs/specs/SpecsWorkflowsPage.tsx
-import Link4 from "@contractspec/lib.ui-link";
-import { ChevronRight as ChevronRight4 } from "lucide-react";
-import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
-function SpecsWorkflowsPage() {
-  return /* @__PURE__ */ jsxs4("div", {
+// src/components/docs/specs/SpecsOverlaysPage.tsx
+import Link3 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight3 } from "lucide-react";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function SpecsOverlaysPage() {
+  return /* @__PURE__ */ jsxs3("div", {
     className: "space-y-8",
     children: [
-      /* @__PURE__ */ jsxs4("div", {
+      /* @__PURE__ */ jsxs3("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx4("h1", {
-            className: "text-4xl font-bold",
-            children: "Workflows"
+          /* @__PURE__ */ jsx3("h1", {
+            className: "font-bold text-4xl",
+            children: "Overlays"
           }),
-          /* @__PURE__ */ jsxs4("p", {
+          /* @__PURE__ */ jsxs3("p", {
             className: "text-muted-foreground",
             children: [
-              "A ",
-              /* @__PURE__ */ jsx4("strong", {
-                children: "WorkflowSpec"
+              "An ",
+              /* @__PURE__ */ jsx3("strong", {
+                children: "OverlaySpec"
               }),
-              " orchestrates multi-step processes. It defines the sequence of operations, handles failures with retries and compensation, and provides observability into long-running tasks."
+              " allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities."
             ]
           })
         ]
       }),
-      /* @__PURE__ */ jsxs4("div", {
+      /* @__PURE__ */ jsxs3("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx4("h2", {
-            className: "text-2xl font-bold",
-            children: "Core concepts"
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "Why overlays matter"
           }),
-          /* @__PURE__ */ jsxs4("div", {
-            className: "space-y-3",
+          /* @__PURE__ */ jsx3("p", {
+            className: "text-muted-foreground",
+            children: "Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use."
+          }),
+          /* @__PURE__ */ jsx3("p", {
+            className: "text-muted-foreground",
+            children: "Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies."
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsxs3("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "What overlays can do"
+          }),
+          /* @__PURE__ */ jsxs3("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
-              /* @__PURE__ */ jsxs4("div", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("h3", {
-                    className: "text-lg font-semibold",
-                    children: "Identifiers"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Hide or show fields"
                   }),
-                  /* @__PURE__ */ jsxs4("p", {
-                    className: "text-muted-foreground",
-                    children: [
-                      "Each workflow has a unique",
-                      " ",
-                      /* @__PURE__ */ jsx4("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
-                        children: "workflowId"
-                      }),
-                      " ",
-                      "and a",
-                      " ",
-                      /* @__PURE__ */ jsx4("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
-                        children: "version"
-                      }),
-                      ". This allows you to run multiple versions of the same workflow simultaneously during migrations or A/B tests."
-                    ]
-                  })
+                  " \u2013 Remove fields from forms or detail views (but only if the user has permission to see them in the first place)"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("div", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("h3", {
-                    className: "text-lg font-semibold",
-                    children: "Steps"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Reorder fields"
                   }),
-                  /* @__PURE__ */ jsxs4("p", {
-                    className: "text-muted-foreground",
-                    children: [
-                      "A workflow is composed of ",
-                      /* @__PURE__ */ jsx4("strong", {
-                        children: "steps"
-                      }),
-                      ". Each step invokes a",
-                      " ",
-                      /* @__PURE__ */ jsx4(Link4, {
-                        href: "/docs/specs/capabilities",
-                        className: "text-violet-400 hover:text-violet-300",
-                        children: "CapabilitySpec"
-                      }),
-                      ", passes inputs, and receives outputs. Steps can run sequentially or in parallel."
-                    ]
-                  })
+                  " \u2013 Change the order in which fields appear"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("div", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("h3", {
-                    className: "text-lg font-semibold",
-                    children: "Transitions"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Rename labels"
                   }),
-                  /* @__PURE__ */ jsxs4("p", {
-                    className: "text-muted-foreground",
-                    children: [
-                      /* @__PURE__ */ jsx4("strong", {
-                        children: "Transitions"
-                      }),
-                      ' define the flow between steps. They can be conditional (e.g., "if payment succeeds, go to step 3; otherwise, go to step 5") or unconditional.'
-                    ]
-                  })
+                  " \u2013 Use different terminology that's more familiar to the user"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("div", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("h3", {
-                    className: "text-lg font-semibold",
-                    children: "Retries"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Change layouts"
                   }),
-                  /* @__PURE__ */ jsx4("p", {
-                    className: "text-muted-foreground",
-                    children: "If a step fails, the workflow can retry it with exponential backoff. You specify the maximum number of retries and the backoff strategy in the spec."
-                  })
+                  " \u2013 Switch between list, grid, or card views"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("div", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("h3", {
-                    className: "text-lg font-semibold",
-                    children: "Compensation"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Add help text"
                   }),
-                  /* @__PURE__ */ jsxs4("p", {
-                    className: "text-muted-foreground",
-                    children: [
-                      "When a workflow fails partway through,",
-                      " ",
-                      /* @__PURE__ */ jsx4("strong", {
-                        children: "compensation"
-                      }),
-                      " steps undo the effects of completed steps (e.g., refunding a payment, releasing a reservation). This ensures consistency even in failure scenarios."
-                    ]
-                  })
+                  " \u2013 Provide context-specific guidance"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("div", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("h3", {
-                    className: "text-lg font-semibold",
-                    children: "SLAs"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Set default values"
                   }),
-                  /* @__PURE__ */ jsx4("p", {
-                    className: "text-muted-foreground",
-                    children: "You can define Service Level Agreements (SLAs) for each step or the entire workflow. If a step exceeds its SLA, the system can trigger alerts or escalations."
-                  })
+                  " \u2013 Pre-fill forms with tenant-specific defaults"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Apply branding"
+                  }),
+                  " \u2013 Customize colors, logos, and styling (within approved themes)"
                 ]
               })
             ]
           })
         ]
       }),
-      /* @__PURE__ */ jsxs4("div", {
+      /* @__PURE__ */ jsxs3("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx4("h2", {
-            className: "text-2xl font-bold",
-            children: "Example WorkflowSpec (TypeScript)"
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "Example OverlaySpec"
           }),
-          /* @__PURE__ */ jsx4("p", {
+          /* @__PURE__ */ jsx3("p", {
             className: "text-muted-foreground",
-            children: "Here's a simplified example of a payment workflow in TypeScript:"
+            children: "Here's an overlay that customizes an order form:"
           }),
-          /* @__PURE__ */ jsx4("div", {
-            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
-            children: /* @__PURE__ */ jsx4("pre", {
-              children: `import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow';
-import { ValidatePaymentMethod, ChargePayment, SendEmail } from './specs';
-
-export const PaymentFlow = defineWorkflow({
-  meta: {
-    key: 'payment.flow',
-    version: '1.0.0',
-    description: 'End-to-end payment processing',
-    owners: ['team-payments'],
-    tags: ['payments'],
-    stability: 'stable',
-  },
-  steps: [
-    {
-      id: 'validate-payment',
-      operation: ValidatePaymentMethod,
-      inputs: (ctx, input) => ({
-        userId: ctx.userId,
-        paymentMethodId: input.paymentMethodId,
-      }),
-      retry: {
-        maxAttempts: 3,
-        backoff: 'exponential',
-      },
-      onSuccess: 'charge-payment',
-      onFailure: 'notify-user',
-    },
-    {
-      id: 'charge-payment',
-      operation: ChargePayment,
-      inputs: (ctx, input, steps) => ({
-        amount: input.amount,
-        paymentMethodId: input.paymentMethodId,
+          /* @__PURE__ */ jsx3("div", {
+            className: "overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",
+            children: /* @__PURE__ */ jsx3("pre", {
+              children: `overlayId: acme-order-form
+version: '1.0.0'.0.0
+appliesTo:
+  capability: createOrder
+  tenantId: acme-corp
+  
+modifications:
+  - type: hideField
+    field: internalNotes
+    reason: "ACME doesn't use internal notes"
+    
+  - type: renameLabel
+    field: customerReference
+    newLabel: "PO Number"
+    
+  - type: reorderFields
+    fields:
+      - customerReference
+      - items
+      - shippingAddress
+      - billingAddress
+      - paymentMethod
+      
+  - type: setDefault
+    field: paymentMethod
+    value: "net30"
+    
+  - type: addHelpText
+    field: customerReference
+    text: "Enter your purchase order number from your procurement system"
+    
+  - type: makeRequired
+    field: customerReference
+    
+signature:
+  algorithm: EdDSA
+  publicKey: "acme-corp-overlay-key"
+  signature: "base64-encoded-signature"`
+            })
+          })
+        ]
       }),
-      compensation: 'refund-payment',
-      onSuccess: 'send-receipt',
-      onFailure: 'notify-admin',
-    },
-    {
-      id: 'send-receipt',
-      operation: SendEmail,
-      inputs: (ctx, input, steps) => ({
-        to: ctx.userEmail,
-        template: 'payment-receipt',
-        data: steps['charge-payment'].output,
+      /* @__PURE__ */ jsxs3("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "Safety guarantees"
+          }),
+          /* @__PURE__ */ jsx3("p", {
+            className: "text-muted-foreground",
+            children: "Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:"
+          }),
+          /* @__PURE__ */ jsxs3("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
+            children: [
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Overlays cannot grant new permissions"
+                  }),
+                  " \u2013 They can only hide or rearrange what the user is already allowed to see"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Overlays cannot bypass validation"
+                  }),
+                  " \u2013 Field types, constraints, and business rules from the underlying spec still apply"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Overlays must be signed"
+                  }),
+                  " \u2013 Only authorized parties (typically tenant admins) can create overlays"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Overlays are versioned"
+                  }),
+                  " \u2013 Changes to overlays are tracked and can be rolled back"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Overlays are audited"
+                  }),
+                  " \u2013 Every overlay application is logged"
+                ]
+              })
+            ]
+          })
+        ]
       }),
-    },
-  ],
-  sla: {
-    maxDuration: 30000, // milliseconds
-    alertOnBreach: true,
-  },
-});`
-            })
+      /* @__PURE__ */ jsxs3("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "Creating overlays"
+          }),
+          /* @__PURE__ */ jsx3("p", {
+            className: "text-muted-foreground",
+            children: "Overlays can be created through:"
+          }),
+          /* @__PURE__ */ jsxs3("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
+            children: [
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Visual editor"
+                  }),
+                  " \u2013 A drag-and-drop interface for non-technical users"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "TypeScript/JSON"
+                  }),
+                  " \u2013 For developers who prefer code"
+                ]
+              }),
+              /* @__PURE__ */ jsxs3("li", {
+                children: [
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "API"
+                  }),
+                  " \u2013 Programmatically create overlays for automation"
+                ]
+              })
+            ]
+          }),
+          /* @__PURE__ */ jsx3("p", {
+            className: "text-muted-foreground",
+            children: "Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay."
+          }),
+          /* @__PURE__ */ jsxs3("p", {
+            className: "text-muted-foreground",
+            children: [
+              "See",
+              " ",
+              /* @__PURE__ */ jsx3(Link3, {
+                href: "/docs/libraries/overlay-engine",
+                className: "text-violet-400 underline",
+                children: "Overlay Engine docs"
+              }),
+              " ",
+              "and the",
+              " ",
+              /* @__PURE__ */ jsx3(Link3, {
+                href: "/docs/advanced/overlay-editor",
+                className: "text-violet-400 underline",
+                children: "Overlay Editor guide"
+              }),
+              " ",
+              "for end-to-end workflows."
+            ]
           })
         ]
       }),
-      /* @__PURE__ */ jsxs4("div", {
+      /* @__PURE__ */ jsxs3("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx4("h2", {
-            className: "text-2xl font-bold",
-            children: "Triggers"
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "Overlay scope"
           }),
-          /* @__PURE__ */ jsx4("p", {
+          /* @__PURE__ */ jsx3("p", {
             className: "text-muted-foreground",
-            children: "Workflows can be triggered in several ways:"
+            children: "Overlays can be scoped to:"
           }),
-          /* @__PURE__ */ jsxs4("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+          /* @__PURE__ */ jsxs3("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
-              /* @__PURE__ */ jsxs4("li", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("strong", {
-                    children: "Manual invocation"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Tenant"
                   }),
-                  " \u2013 A user or system calls the workflow via an API endpoint."
+                  " \u2013 All users in a tenant see the same overlay"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("li", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("strong", {
-                    children: "Event-driven"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "User"
                   }),
-                  " \u2013 The workflow starts automatically when a specific event occurs (e.g., a new order is created)."
+                  " \u2013 Individual users can have personal overlays"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("li", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("strong", {
-                    children: "Scheduled"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Role"
                   }),
-                  " \u2013 The workflow runs on a cron schedule (e.g., nightly batch processing)."
+                  " \u2013 All users with a specific role see the overlay"
                 ]
               }),
-              /* @__PURE__ */ jsxs4("li", {
+              /* @__PURE__ */ jsxs3("li", {
                 children: [
-                  /* @__PURE__ */ jsx4("strong", {
-                    children: "Chained"
+                  /* @__PURE__ */ jsx3("strong", {
+                    children: "Device"
                   }),
-                  " \u2013 One workflow can invoke another as a step."
+                  " \u2013 Different overlays for mobile vs desktop"
                 ]
               })
             ]
+          }),
+          /* @__PURE__ */ jsx3("p", {
+            className: "text-muted-foreground",
+            children: "If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays)."
           })
         ]
       }),
-      /* @__PURE__ */ jsxs4("div", {
+      /* @__PURE__ */ jsxs3("div", {
         className: "space-y-4",
         children: [
-          /* @__PURE__ */ jsx4("h2", {
-            className: "text-2xl font-bold",
-            children: "Monitoring and versioning"
-          }),
-          /* @__PURE__ */ jsx4("p", {
-            className: "text-muted-foreground",
-            children: "ContractSpec automatically instruments workflows with telemetry. You can view:"
+          /* @__PURE__ */ jsx3("h2", {
+            className: "font-bold text-2xl",
+            children: "Best practices"
           }),
-          /* @__PURE__ */ jsxs4("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+          /* @__PURE__ */ jsxs3("ul", {
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
-              /* @__PURE__ */ jsx4("li", {
-                children: "Real-time execution status for each step"
+              /* @__PURE__ */ jsx3("li", {
+                children: "Start with the default UI and only create overlays when users request specific changes."
               }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Historical run data and success/failure rates"
+              /* @__PURE__ */ jsx3("li", {
+                children: "Document why each overlay modification was made\u2014this helps when reviewing or updating overlays."
               }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Latency distributions and SLA compliance"
+              /* @__PURE__ */ jsx3("li", {
+                children: "Test overlays thoroughly to ensure they don't break workflows or confuse users."
               }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Compensation events and retry attempts"
+              /* @__PURE__ */ jsx3("li", {
+                children: "Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences."
+              }),
+              /* @__PURE__ */ jsx3("li", {
+                children: "Regularly review overlays to remove ones that are no longer needed."
+              }),
+              /* @__PURE__ */ jsx3("li", {
+                children: "Protect overlay signing keys carefully\u2014they control what customizations are allowed."
+              })
+            ]
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsxs3("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsx3(Link3, {
+            href: "/docs/specs/policy",
+            className: "btn-ghost",
+            children: "Previous: Policy"
+          }),
+          /* @__PURE__ */ jsxs3(Link3, {
+            href: "/docs/safety",
+            className: "btn-primary",
+            children: [
+              "Next: Safety ",
+              /* @__PURE__ */ jsx3(ChevronRight3, {
+                size: 16
               })
             ]
+          })
+        ]
+      })
+    ]
+  });
+}
+
+// src/components/docs/specs/SpecsOverviewPage.tsx
+import Link4 from "@contractspec/lib.ui-link";
+import { ChevronRight as ChevronRight4 } from "lucide-react";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+var specTypes = [
+  {
+    title: "Capabilities",
+    body: "Model operations, events, and presentations as explicit system behavior.",
+    href: "/docs/specs/capabilities"
+  },
+  {
+    title: "Data views",
+    body: "Describe query, filtering, and presentation behavior from the same source model.",
+    href: "/docs/specs/dataviews"
+  },
+  {
+    title: "Workflows",
+    body: "Coordinate multi-step execution, retries, monitoring, and hand-offs.",
+    href: "/docs/specs/workflows"
+  },
+  {
+    title: "Policy",
+    body: "Carry governance and access rules through every generated and runtime-served surface.",
+    href: "/docs/specs/policy"
+  },
+  {
+    title: "Overlays",
+    body: "Customize generated surfaces safely instead of forking them permanently.",
+    href: "/docs/specs/overlays"
+  },
+  {
+    title: "Safety and migration",
+    body: "Keep change safe with signing, audits, rollbacks, and explicit migration behavior.",
+    href: "/docs/safety"
+  }
+];
+function SpecsOverviewPage() {
+  return /* @__PURE__ */ jsxs4("div", {
+    className: "space-y-10",
+    children: [
+      /* @__PURE__ */ jsxs4("div", {
+        className: "space-y-3",
+        children: [
+          /* @__PURE__ */ jsx4("p", {
+            className: "editorial-kicker",
+            children: "Core model"
+          }),
+          /* @__PURE__ */ jsx4("h1", {
+            className: "font-serif text-4xl tracking-[-0.04em] md:text-5xl",
+            children: "Contracts are the durable system boundary."
           }),
           /* @__PURE__ */ jsx4("p", {
-            className: "text-muted-foreground",
-            children: "When you update a workflow, you increment its version. Running workflows continue on their original version, while new invocations use the latest version. This allows safe, zero-downtime deployments."
+            className: "max-w-3xl text-lg text-muted-foreground leading-8",
+            children: "ContractSpec uses explicit TypeScript specs to describe behavior before it spreads across APIs, UI, data models, events, and operator flows. The goal is not to hide implementation. The goal is to make the system boundary explicit enough that generation, validation, runtime enforcement, and regeneration can stay coherent."
           })
         ]
       }),
       /* @__PURE__ */ jsxs4("div", {
-        className: "space-y-4",
+        className: "editorial-proof-strip",
         children: [
-          /* @__PURE__ */ jsx4("h2", {
-            className: "text-2xl font-bold",
-            children: "Best practices"
-          }),
-          /* @__PURE__ */ jsxs4("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+          /* @__PURE__ */ jsxs4("div", {
+            className: "editorial-stat",
             children: [
-              /* @__PURE__ */ jsx4("li", {
-                children: "Keep steps idempotent \u2013 they should be safe to retry without side effects."
-              }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Define compensation for any step that modifies external state."
-              }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Use meaningful step IDs that describe the operation."
-              }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Set realistic SLAs and monitor them in production."
+              /* @__PURE__ */ jsx4("span", {
+                className: "editorial-label",
+                children: "System promise"
               }),
-              /* @__PURE__ */ jsx4("li", {
-                children: "Test failure scenarios locally before deploying."
+              /* @__PURE__ */ jsx4("span", {
+                className: "editorial-stat-value",
+                children: "one contract \u2192 many surfaces"
               })
             ]
+          }),
+          /* @__PURE__ */ jsx4("p", {
+            className: "max-w-2xl text-muted-foreground text-sm leading-7",
+            children: "Use the contract layer to keep surface behavior aligned, then let runtimes and generators do the repetitive work without inventing a closed platform."
           })
         ]
       }),
-      /* @__PURE__ */ jsxs4("div", {
-        className: "flex items-center gap-4 pt-4",
+      /* @__PURE__ */ jsx4("section", {
+        className: "editorial-panel space-y-5",
+        children: /* @__PURE__ */ jsxs4("div", {
+          className: "space-y-2",
+          children: [
+            /* @__PURE__ */ jsx4("h2", {
+              className: "font-serif text-3xl tracking-[-0.03em]",
+              children: "What the contract layer owns"
+            }),
+            /* @__PURE__ */ jsxs4("ul", {
+              className: "editorial-list",
+              children: [
+                /* @__PURE__ */ jsxs4("li", {
+                  children: [
+                    /* @__PURE__ */ jsx4("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx4("span", {
+                      children: "Behavior: operations, events, presentations, workflows."
+                    })
+                  ]
+                }),
+                /* @__PURE__ */ jsxs4("li", {
+                  children: [
+                    /* @__PURE__ */ jsx4("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx4("span", {
+                      children: "Validation: input, output, and schema boundaries."
+                    })
+                  ]
+                }),
+                /* @__PURE__ */ jsxs4("li", {
+                  children: [
+                    /* @__PURE__ */ jsx4("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx4("span", {
+                      children: "Governance: policy, auditability, and migration rules."
+                    })
+                  ]
+                }),
+                /* @__PURE__ */ jsxs4("li", {
+                  children: [
+                    /* @__PURE__ */ jsx4("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx4("span", {
+                      children: "Surface alignment: generated or served behavior across API, UI, data, and agent-facing interfaces."
+                    })
+                  ]
+                })
+              ]
+            })
+          ]
+        })
+      }),
+      /* @__PURE__ */ jsxs4("section", {
+        className: "space-y-5",
         children: [
-          /* @__PURE__ */ jsx4(Link4, {
-            href: "/docs/specs/capabilities",
-            className: "btn-ghost",
-            children: "Previous: Capabilities"
-          }),
-          /* @__PURE__ */ jsxs4(Link4, {
-            href: "/docs/safety",
-            className: "btn-primary",
+          /* @__PURE__ */ jsxs4("div", {
+            className: "space-y-2",
             children: [
-              "Next: Safety Features ",
-              /* @__PURE__ */ jsx4(ChevronRight4, {
-                size: 16
+              /* @__PURE__ */ jsx4("h2", {
+                className: "font-serif text-3xl tracking-[-0.03em]",
+                children: "Specification types"
+              }),
+              /* @__PURE__ */ jsx4("p", {
+                className: "text-muted-foreground text-sm leading-7",
+                children: "You can adopt the model one part at a time. Not every system needs every spec type on day one."
               })
             ]
+          }),
+          /* @__PURE__ */ jsx4("div", {
+            className: "grid gap-4 md:grid-cols-2",
+            children: specTypes.map((item) => /* @__PURE__ */ jsxs4(Link4, {
+              href: item.href,
+              className: "editorial-panel",
+              children: [
+                /* @__PURE__ */ jsx4("h3", {
+                  className: "font-semibold text-xl",
+                  children: item.title
+                }),
+                /* @__PURE__ */ jsx4("p", {
+                  className: "mt-2 text-muted-foreground text-sm leading-7",
+                  children: item.body
+                }),
+                /* @__PURE__ */ jsxs4("div", {
+                  className: "mt-4 flex items-center gap-2 text-[color:var(--rust)] text-sm",
+                  children: [
+                    "Open section ",
+                    /* @__PURE__ */ jsx4(ChevronRight4, {
+                      size: 14
+                    })
+                  ]
+                })
+              ]
+            }, item.title))
           })
         ]
       })
@@ -1208,7 +1091,7 @@ function SpecsPolicyPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h1", {
-            className: "text-4xl font-bold",
+            className: "font-bold text-4xl",
             children: "Policy"
           }),
           /* @__PURE__ */ jsxs5("p", {
@@ -1227,7 +1110,7 @@ function SpecsPolicyPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Why policies matter"
           }),
           /* @__PURE__ */ jsx5("p", {
@@ -1254,7 +1137,7 @@ function SpecsPolicyPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Policy structure"
           }),
           /* @__PURE__ */ jsx5("p", {
@@ -1262,7 +1145,7 @@ function SpecsPolicyPage() {
             children: "A PolicySpec contains one or more rules. Each rule has:"
           }),
           /* @__PURE__ */ jsxs5("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
               /* @__PURE__ */ jsxs5("li", {
                 children: [
@@ -1304,7 +1187,7 @@ function SpecsPolicyPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Example PolicySpec"
           }),
           /* @__PURE__ */ jsx5("p", {
@@ -1312,7 +1195,7 @@ function SpecsPolicyPage() {
             children: "Here's a policy that controls access to customer data in TypeScript:"
           }),
           /* @__PURE__ */ jsx5("div", {
-            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
+            className: "overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",
             children: /* @__PURE__ */ jsx5("pre", {
               children: `import { definePolicy } from '@contractspec/lib.contracts-spec';
 
@@ -1365,7 +1248,7 @@ export const CustomerDataAccess = definePolicy({
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Attributes"
           }),
           /* @__PURE__ */ jsx5("p", {
@@ -1378,32 +1261,32 @@ export const CustomerDataAccess = definePolicy({
               /* @__PURE__ */ jsxs5("div", {
                 children: [
                   /* @__PURE__ */ jsx5("h3", {
-                    className: "text-lg font-semibold",
+                    className: "font-semibold text-lg",
                     children: "User attributes"
                   }),
                   /* @__PURE__ */ jsxs5("p", {
                     className: "text-muted-foreground",
                     children: [
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "user.id"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "user.role"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "user.groups"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "user.department"
                       }),
                       ", custom attributes"
@@ -1414,26 +1297,26 @@ export const CustomerDataAccess = definePolicy({
               /* @__PURE__ */ jsxs5("div", {
                 children: [
                   /* @__PURE__ */ jsx5("h3", {
-                    className: "text-lg font-semibold",
+                    className: "font-semibold text-lg",
                     children: "Resource attributes"
                   }),
                   /* @__PURE__ */ jsxs5("p", {
                     className: "text-muted-foreground",
                     children: [
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "resource.type"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "resource.owner"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "resource.sensitivity"
                       }),
                       ", custom attributes"
@@ -1444,14 +1327,14 @@ export const CustomerDataAccess = definePolicy({
               /* @__PURE__ */ jsxs5("div", {
                 children: [
                   /* @__PURE__ */ jsx5("h3", {
-                    className: "text-lg font-semibold",
+                    className: "font-semibold text-lg",
                     children: "Action attributes"
                   }),
                   /* @__PURE__ */ jsxs5("p", {
                     className: "text-muted-foreground",
                     children: [
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "action"
                       }),
                       " ",
@@ -1463,32 +1346,32 @@ export const CustomerDataAccess = definePolicy({
               /* @__PURE__ */ jsxs5("div", {
                 children: [
                   /* @__PURE__ */ jsx5("h3", {
-                    className: "text-lg font-semibold",
+                    className: "font-semibold text-lg",
                     children: "Context attributes"
                   }),
                   /* @__PURE__ */ jsxs5("p", {
                     className: "text-muted-foreground",
                     children: [
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "time.hour"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "time.dayOfWeek"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "request.ipAddress"
                       }),
                       ",",
                       " ",
                       /* @__PURE__ */ jsx5("code", {
-                        className: "bg-background/50 rounded px-2 py-1",
+                        className: "rounded bg-background/50 px-2 py-1",
                         children: "request.userAgent"
                       })
                     ]
@@ -1503,7 +1386,7 @@ export const CustomerDataAccess = definePolicy({
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Data classification"
           }),
           /* @__PURE__ */ jsxs5("p", {
@@ -1528,7 +1411,7 @@ export const CustomerDataAccess = definePolicy({
             ]
           }),
           /* @__PURE__ */ jsx5("div", {
-            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
+            className: "overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",
             children: /* @__PURE__ */ jsx5("pre", {
               children: `fields:
   - name: email
@@ -1556,7 +1439,7 @@ export const CustomerDataAccess = definePolicy({
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Testing policies"
           }),
           /* @__PURE__ */ jsx5("p", {
@@ -1564,7 +1447,7 @@ export const CustomerDataAccess = definePolicy({
             children: "ContractSpec provides tools for testing policies before deployment:"
           }),
           /* @__PURE__ */ jsxs5("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
               /* @__PURE__ */ jsxs5("li", {
                 children: [
@@ -1606,11 +1489,11 @@ export const CustomerDataAccess = definePolicy({
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx5("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Best practices"
           }),
           /* @__PURE__ */ jsxs5("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
               /* @__PURE__ */ jsx5("li", {
                 children: "Start with a deny-by-default policy\u2014explicitly permit what should be allowed."
@@ -1667,11 +1550,11 @@ export const CustomerDataAccess = definePolicy({
   });
 }
 
-// src/components/docs/specs/SpecsOverlaysPage.tsx
+// src/components/docs/specs/SpecsWorkflowsPage.tsx
 import Link6 from "@contractspec/lib.ui-link";
 import { ChevronRight as ChevronRight6 } from "lucide-react";
 import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
-function SpecsOverlaysPage() {
+function SpecsWorkflowsPage() {
   return /* @__PURE__ */ jsxs6("div", {
     className: "space-y-8",
     children: [
@@ -1679,17 +1562,17 @@ function SpecsOverlaysPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx6("h1", {
-            className: "text-4xl font-bold",
-            children: "Overlays"
+            className: "font-bold text-4xl",
+            children: "Workflows"
           }),
           /* @__PURE__ */ jsxs6("p", {
             className: "text-muted-foreground",
             children: [
-              "An ",
+              "A ",
               /* @__PURE__ */ jsx6("strong", {
-                children: "OverlaySpec"
+                children: "WorkflowSpec"
               }),
-              " allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities."
+              " orchestrates multi-step processes. It defines the sequence of operations, handles failures with retries and compensation, and provides observability into long-running tasks."
             ]
           })
         ]
@@ -1698,83 +1581,122 @@ function SpecsOverlaysPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
-            children: "Why overlays matter"
-          }),
-          /* @__PURE__ */ jsx6("p", {
-            className: "text-muted-foreground",
-            children: "Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use."
-          }),
-          /* @__PURE__ */ jsx6("p", {
-            className: "text-muted-foreground",
-            children: "Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies."
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs6("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
-            children: "What overlays can do"
+            className: "font-bold text-2xl",
+            children: "Core concepts"
           }),
-          /* @__PURE__ */ jsxs6("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+          /* @__PURE__ */ jsxs6("div", {
+            className: "space-y-3",
             children: [
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Hide or show fields"
-                  }),
-                  " \u2013 Remove fields from forms or detail views (but only if the user has permission to see them in the first place)"
-                ]
-              }),
-              /* @__PURE__ */ jsxs6("li", {
+              /* @__PURE__ */ jsxs6("div", {
                 children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Reorder fields"
+                  /* @__PURE__ */ jsx6("h3", {
+                    className: "font-semibold text-lg",
+                    children: "Identifiers"
                   }),
-                  " \u2013 Change the order in which fields appear"
+                  /* @__PURE__ */ jsxs6("p", {
+                    className: "text-muted-foreground",
+                    children: [
+                      "Each workflow has a unique",
+                      " ",
+                      /* @__PURE__ */ jsx6("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
+                        children: "workflowId"
+                      }),
+                      " ",
+                      "and a",
+                      " ",
+                      /* @__PURE__ */ jsx6("code", {
+                        className: "rounded bg-background/50 px-2 py-1",
+                        children: "version"
+                      }),
+                      ". This allows you to run multiple versions of the same workflow simultaneously during migrations or A/B tests."
+                    ]
+                  })
                 ]
               }),
-              /* @__PURE__ */ jsxs6("li", {
+              /* @__PURE__ */ jsxs6("div", {
                 children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Rename labels"
+                  /* @__PURE__ */ jsx6("h3", {
+                    className: "font-semibold text-lg",
+                    children: "Steps"
                   }),
-                  " \u2013 Use different terminology that's more familiar to the user"
+                  /* @__PURE__ */ jsxs6("p", {
+                    className: "text-muted-foreground",
+                    children: [
+                      "A workflow is composed of ",
+                      /* @__PURE__ */ jsx6("strong", {
+                        children: "steps"
+                      }),
+                      ". Each step invokes a",
+                      " ",
+                      /* @__PURE__ */ jsx6(Link6, {
+                        href: "/docs/specs/capabilities",
+                        className: "text-violet-400 hover:text-violet-300",
+                        children: "CapabilitySpec"
+                      }),
+                      ", passes inputs, and receives outputs. Steps can run sequentially or in parallel."
+                    ]
+                  })
                 ]
               }),
-              /* @__PURE__ */ jsxs6("li", {
+              /* @__PURE__ */ jsxs6("div", {
                 children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Change layouts"
+                  /* @__PURE__ */ jsx6("h3", {
+                    className: "font-semibold text-lg",
+                    children: "Transitions"
                   }),
-                  " \u2013 Switch between list, grid, or card views"
+                  /* @__PURE__ */ jsxs6("p", {
+                    className: "text-muted-foreground",
+                    children: [
+                      /* @__PURE__ */ jsx6("strong", {
+                        children: "Transitions"
+                      }),
+                      ' define the flow between steps. They can be conditional (e.g., "if payment succeeds, go to step 3; otherwise, go to step 5") or unconditional.'
+                    ]
+                  })
                 ]
               }),
-              /* @__PURE__ */ jsxs6("li", {
+              /* @__PURE__ */ jsxs6("div", {
                 children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Add help text"
+                  /* @__PURE__ */ jsx6("h3", {
+                    className: "font-semibold text-lg",
+                    children: "Retries"
                   }),
-                  " \u2013 Provide context-specific guidance"
+                  /* @__PURE__ */ jsx6("p", {
+                    className: "text-muted-foreground",
+                    children: "If a step fails, the workflow can retry it with exponential backoff. You specify the maximum number of retries and the backoff strategy in the spec."
+                  })
                 ]
               }),
-              /* @__PURE__ */ jsxs6("li", {
+              /* @__PURE__ */ jsxs6("div", {
                 children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Set default values"
+                  /* @__PURE__ */ jsx6("h3", {
+                    className: "font-semibold text-lg",
+                    children: "Compensation"
                   }),
-                  " \u2013 Pre-fill forms with tenant-specific defaults"
+                  /* @__PURE__ */ jsxs6("p", {
+                    className: "text-muted-foreground",
+                    children: [
+                      "When a workflow fails partway through,",
+                      " ",
+                      /* @__PURE__ */ jsx6("strong", {
+                        children: "compensation"
+                      }),
+                      " steps undo the effects of completed steps (e.g., refunding a payment, releasing a reservation). This ensures consistency even in failure scenarios."
+                    ]
+                  })
                 ]
               }),
-              /* @__PURE__ */ jsxs6("li", {
+              /* @__PURE__ */ jsxs6("div", {
                 children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Apply branding"
+                  /* @__PURE__ */ jsx6("h3", {
+                    className: "font-semibold text-lg",
+                    children: "SLAs"
                   }),
-                  " \u2013 Customize colors, logos, and styling (within approved themes)"
+                  /* @__PURE__ */ jsx6("p", {
+                    className: "text-muted-foreground",
+                    children: "You can define Service Level Agreements (SLAs) for each step or the entire workflow. If a step exceeds its SLA, the system can trigger alerts or escalations."
+                  })
                 ]
               })
             ]
@@ -1785,54 +1707,69 @@ function SpecsOverlaysPage() {
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
-            children: "Example OverlaySpec"
+            className: "font-bold text-2xl",
+            children: "Example WorkflowSpec (TypeScript)"
           }),
           /* @__PURE__ */ jsx6("p", {
             className: "text-muted-foreground",
-            children: "Here's an overlay that customizes an order form:"
+            children: "Here's a simplified example of a payment workflow in TypeScript:"
           }),
           /* @__PURE__ */ jsx6("div", {
-            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
+            className: "overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",
             children: /* @__PURE__ */ jsx6("pre", {
-              children: `overlayId: acme-order-form
-version: '1.0.0'.0.0
-appliesTo:
-  capability: createOrder
-  tenantId: acme-corp
-  
-modifications:
-  - type: hideField
-    field: internalNotes
-    reason: "ACME doesn't use internal notes"
-    
-  - type: renameLabel
-    field: customerReference
-    newLabel: "PO Number"
-    
-  - type: reorderFields
-    fields:
-      - customerReference
-      - items
-      - shippingAddress
-      - billingAddress
-      - paymentMethod
-      
-  - type: setDefault
-    field: paymentMethod
-    value: "net30"
-    
-  - type: addHelpText
-    field: customerReference
-    text: "Enter your purchase order number from your procurement system"
-    
-  - type: makeRequired
-    field: customerReference
-    
-signature:
-  algorithm: EdDSA
-  publicKey: "acme-corp-overlay-key"
-  signature: "base64-encoded-signature"`
+              children: `import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow';
+import { ValidatePaymentMethod, ChargePayment, SendEmail } from './specs';
+
+export const PaymentFlow = defineWorkflow({
+  meta: {
+    key: 'payment.flow',
+    version: '1.0.0',
+    description: 'End-to-end payment processing',
+    owners: ['team-payments'],
+    tags: ['payments'],
+    stability: 'stable',
+  },
+  steps: [
+    {
+      id: 'validate-payment',
+      operation: ValidatePaymentMethod,
+      inputs: (ctx, input) => ({
+        userId: ctx.userId,
+        paymentMethodId: input.paymentMethodId,
+      }),
+      retry: {
+        maxAttempts: 3,
+        backoff: 'exponential',
+      },
+      onSuccess: 'charge-payment',
+      onFailure: 'notify-user',
+    },
+    {
+      id: 'charge-payment',
+      operation: ChargePayment,
+      inputs: (ctx, input, steps) => ({
+        amount: input.amount,
+        paymentMethodId: input.paymentMethodId,
+      }),
+      compensation: 'refund-payment',
+      onSuccess: 'send-receipt',
+      onFailure: 'notify-admin',
+    },
+    {
+      id: 'send-receipt',
+      operation: SendEmail,
+      inputs: (ctx, input, steps) => ({
+        to: ctx.userEmail,
+        template: 'payment-receipt',
+        data: steps['charge-payment'].output,
+      }),
+    },
+  ],
+  sla: {
+    maxDuration: 30000, // milliseconds
+    alertOnBreach: true,
+  },
+});`
             })
           })
         ]
@@ -1841,125 +1778,49 @@ signature:
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
-            children: "Safety guarantees"
+            className: "font-bold text-2xl",
+            children: "Triggers"
           }),
           /* @__PURE__ */ jsx6("p", {
             className: "text-muted-foreground",
-            children: "Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:"
+            children: "Workflows can be triggered in several ways:"
           }),
           /* @__PURE__ */ jsxs6("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
               /* @__PURE__ */ jsxs6("li", {
                 children: [
                   /* @__PURE__ */ jsx6("strong", {
-                    children: "Overlays cannot grant new permissions"
-                  }),
-                  " \u2013 They can only hide or rearrange what the user is already allowed to see"
-                ]
-              }),
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Overlays cannot bypass validation"
-                  }),
-                  " \u2013 Field types, constraints, and business rules from the underlying spec still apply"
-                ]
-              }),
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Overlays must be signed"
-                  }),
-                  " \u2013 Only authorized parties (typically tenant admins) can create overlays"
-                ]
-              }),
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Overlays are versioned"
+                    children: "Manual invocation"
                   }),
-                  " \u2013 Changes to overlays are tracked and can be rolled back"
+                  " \u2013 A user or system calls the workflow via an API endpoint."
                 ]
               }),
               /* @__PURE__ */ jsxs6("li", {
                 children: [
                   /* @__PURE__ */ jsx6("strong", {
-                    children: "Overlays are audited"
-                  }),
-                  " \u2013 Every overlay application is logged"
-                ]
-              })
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs6("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
-            children: "Creating overlays"
-          }),
-          /* @__PURE__ */ jsx6("p", {
-            className: "text-muted-foreground",
-            children: "Overlays can be created through:"
-          }),
-          /* @__PURE__ */ jsxs6("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
-            children: [
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Visual editor"
+                    children: "Event-driven"
                   }),
-                  " \u2013 A drag-and-drop interface for non-technical users"
+                  " \u2013 The workflow starts automatically when a specific event occurs (e.g., a new order is created)."
                 ]
               }),
               /* @__PURE__ */ jsxs6("li", {
                 children: [
                   /* @__PURE__ */ jsx6("strong", {
-                    children: "TypeScript/JSON"
+                    children: "Scheduled"
                   }),
-                  " \u2013 For developers who prefer code"
+                  " \u2013 The workflow runs on a cron schedule (e.g., nightly batch processing)."
                 ]
               }),
               /* @__PURE__ */ jsxs6("li", {
                 children: [
                   /* @__PURE__ */ jsx6("strong", {
-                    children: "API"
+                    children: "Chained"
                   }),
-                  " \u2013 Programmatically create overlays for automation"
+                  " \u2013 One workflow can invoke another as a step."
                 ]
               })
             ]
-          }),
-          /* @__PURE__ */ jsx6("p", {
-            className: "text-muted-foreground",
-            children: "Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay."
-          }),
-          /* @__PURE__ */ jsxs6("p", {
-            className: "text-muted-foreground",
-            children: [
-              "See",
-              " ",
-              /* @__PURE__ */ jsx6(Link6, {
-                href: "/docs/libraries/overlay-engine",
-                className: "text-violet-400 underline",
-                children: "Overlay Engine docs"
-              }),
-              " ",
-              "and the",
-              " ",
-              /* @__PURE__ */ jsx6(Link6, {
-                href: "/docs/advanced/overlay-editor",
-                className: "text-violet-400 underline",
-                children: "Overlay Editor guide"
-              }),
-              " ",
-              "for end-to-end workflows."
-            ]
           })
         ]
       }),
@@ -1967,53 +1828,33 @@ signature:
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
-            children: "Overlay scope"
+            className: "font-bold text-2xl",
+            children: "Monitoring and versioning"
           }),
           /* @__PURE__ */ jsx6("p", {
             className: "text-muted-foreground",
-            children: "Overlays can be scoped to:"
+            children: "ContractSpec automatically instruments workflows with telemetry. You can view:"
           }),
           /* @__PURE__ */ jsxs6("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Tenant"
-                  }),
-                  " \u2013 All users in a tenant see the same overlay"
-                ]
+              /* @__PURE__ */ jsx6("li", {
+                children: "Real-time execution status for each step"
               }),
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "User"
-                  }),
-                  " \u2013 Individual users can have personal overlays"
-                ]
+              /* @__PURE__ */ jsx6("li", {
+                children: "Historical run data and success/failure rates"
               }),
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Role"
-                  }),
-                  " \u2013 All users with a specific role see the overlay"
-                ]
+              /* @__PURE__ */ jsx6("li", {
+                children: "Latency distributions and SLA compliance"
               }),
-              /* @__PURE__ */ jsxs6("li", {
-                children: [
-                  /* @__PURE__ */ jsx6("strong", {
-                    children: "Device"
-                  }),
-                  " \u2013 Different overlays for mobile vs desktop"
-                ]
+              /* @__PURE__ */ jsx6("li", {
+                children: "Compensation events and retry attempts"
               })
             ]
           }),
           /* @__PURE__ */ jsx6("p", {
             className: "text-muted-foreground",
-            children: "If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays)."
+            children: "When you update a workflow, you increment its version. Running workflows continue on their original version, while new invocations use the latest version. This allows safe, zero-downtime deployments."
           })
         ]
       }),
@@ -2021,29 +1862,26 @@ signature:
         className: "space-y-4",
         children: [
           /* @__PURE__ */ jsx6("h2", {
-            className: "text-2xl font-bold",
+            className: "font-bold text-2xl",
             children: "Best practices"
           }),
           /* @__PURE__ */ jsxs6("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
+            className: "list-inside list-disc space-y-2 text-muted-foreground",
             children: [
               /* @__PURE__ */ jsx6("li", {
-                children: "Start with the default UI and only create overlays when users request specific changes."
-              }),
-              /* @__PURE__ */ jsx6("li", {
-                children: "Document why each overlay modification was made\u2014this helps when reviewing or updating overlays."
+                children: "Keep steps idempotent \u2013 they should be safe to retry without side effects."
               }),
               /* @__PURE__ */ jsx6("li", {
-                children: "Test overlays thoroughly to ensure they don't break workflows or confuse users."
+                children: "Define compensation for any step that modifies external state."
               }),
               /* @__PURE__ */ jsx6("li", {
-                children: "Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences."
+                children: "Use meaningful step IDs that describe the operation."
               }),
               /* @__PURE__ */ jsx6("li", {
-                children: "Regularly review overlays to remove ones that are no longer needed."
+                children: "Set realistic SLAs and monitor them in production."
               }),
               /* @__PURE__ */ jsx6("li", {
-                children: "Protect overlay signing keys carefully\u2014they control what customizations are allowed."
+                children: "Test failure scenarios locally before deploying."
               })
             ]
           })
@@ -2053,15 +1891,15 @@ signature:
         className: "flex items-center gap-4 pt-4",
         children: [
           /* @__PURE__ */ jsx6(Link6, {
-            href: "/docs/specs/policy",
+            href: "/docs/specs/capabilities",
             className: "btn-ghost",
-            children: "Previous: Policy"
+            children: "Previous: Capabilities"
           }),
           /* @__PURE__ */ jsxs6(Link6, {
             href: "/docs/safety",
             className: "btn-primary",
             children: [
-              "Next: Safety ",
+              "Next: Safety Features ",
               /* @__PURE__ */ jsx6(ChevronRight6, {
                 size: 16
               })