@contractspec/bundle.library 3.8.11 → 3.9.0

package/src/components/docs/libraries/LibrariesContractsPage.tsx

@@ -2,6 +2,55 @@ import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const DATA_TABLE_CONTRACT_EXAMPLE = `import { defineDataView } from '@contractspec/lib.contracts-spec/data-views';
+import { ListDataGridShowcaseRowsQuery } from '@contractspec/example.data-grid-showcase/contracts/data-grid-showcase.operation';
+
+export const DataGridShowcaseDataView = defineDataView({
+  meta: {
+    key: 'examples.data-grid-showcase.table',
+    version: '1.0.0',
+    entity: 'account',
+    title: 'Data Grid Showcase Table',
+    description:
+      'Declarative DataViewSpec for the ContractSpec table showcase.',
+    domain: 'examples',
+    owners: ['@platform.core'],
+    tags: ['examples', 'table', 'data-grid'],
+    stability: 'experimental',
+  },
+  source: {
+    primary: {
+      key: ListDataGridShowcaseRowsQuery.meta.key,
+      version: ListDataGridShowcaseRowsQuery.meta.version,
+    },
+  },
+  view: {
+    kind: 'table',
+    executionMode: 'client',
+    selection: 'multiple',
+    columnVisibility: true,
+    columnResizing: true,
+    columnPinning: true,
+    rowExpansion: {
+      fields: ['notes', 'renewalDate', 'lastActivityAt'],
+    },
+    initialState: {
+      pageSize: 4,
+      hiddenColumns: ['notes'],
+      pinnedColumns: {
+        left: ['account'],
+      },
+      sorting: [{ field: 'arr', desc: true }],
+    },
+    fields: [
+      { key: 'account', label: 'Account', dataPath: 'account', sortable: true },
+      { key: 'owner', label: 'Owner', dataPath: 'owner', sortable: true },
+      { key: 'status', label: 'Status', dataPath: 'status', sortable: true },
+      { key: 'notes', label: 'Notes', dataPath: 'notes' },
+    ],
+  },
+});`;
+
 export function LibrariesContractsPage() {
 	return (
 		<div className="space-y-8">
@@ -47,33 +96,24 @@ export function LibrariesContractsPage() {
 			</div>
 
 			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Quick Example</h2>
-				<CodeBlock
-					language="typescript"
-					code={`import { defineCommand } from '@contractspec/lib.contracts-spec';
-import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
-
-const CreateUserInput = new SchemaModel({
-  name: 'CreateUserInput',
-  fields: {
-    email: { type: ScalarTypeEnum.Email(), isOptional: false },
-    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
-  },
-});
-
-export const CreateUser = defineCommand({
-  meta: {
-    key: 'users.createUser',
-    version: '1.0.0',
-    description: 'Create a new user account',
-  },
-  io: {
-    input: CreateUserInput,
-    output: /* ... */,
-  },
-  policy: { auth: 'admin' },
-});`}
-				/>
+				<h2 className="font-bold text-2xl">Data table contract example</h2>
+				<p className="text-muted-foreground">
+					The canonical account-grid example starts here in{' '}
+					<code>@contractspec/lib.contracts-spec</code>. The contract declares
+					table execution mode, selection, pinning, resizing, row expansion, and
+					initial state before any renderer is chosen.
+				</p>
+				<CodeBlock language="typescript" code={DATA_TABLE_CONTRACT_EXAMPLE} />
+				<p className="text-muted-foreground text-sm">
+					See the live version in{' '}
+					<Link
+						href="/docs/examples/data-grid-showcase"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						/docs/examples/data-grid-showcase
+					</Link>
+					.
+				</p>
 			</div>
 
 			<div className="space-y-4">
@@ -104,6 +144,11 @@ export const CreateUser = defineCommand({
 						<strong>PresentationSpec (V2)</strong>: Describes how data is
 						rendered (Web Components, Markdown, Data).
 					</li>
+					<li>
+						<strong>DataViewSpec</strong>: Declarative list, table, grid, and
+						detail contracts that the table showcase uses as its canonical
+						account-grid example.
+					</li>
 				</ul>
 			</div>
 

package/src/components/docs/libraries/LibrariesDesignSystemPage.tsx

@@ -2,6 +2,56 @@ import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const DESIGN_SYSTEM_TABLE_EXAMPLE = `import { Button, DataTable } from '@contractspec/lib.design-system';
+import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
+
+import { SHOWCASE_ROWS } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.data';
+import { useShowcaseColumns } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.columns';
+import {
+  ExpandedRowContent,
+  ShowcaseToolbar,
+} from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.parts';
+
+export function AccountHealthTable() {
+  const columns = useShowcaseColumns();
+
+  const controller = useContractTable({
+    data: SHOWCASE_ROWS,
+    columns,
+    selectionMode: 'multiple',
+    initialState: {
+      sorting: [{ id: 'arr', desc: true }],
+      pagination: { pageIndex: 0, pageSize: 4 },
+      columnVisibility: { notes: false },
+      columnPinning: { left: ['account'], right: [] },
+    },
+    renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
+    getCanExpand: () => true,
+  });
+
+  return (
+    <DataTable
+      controller={controller}
+      title="Account health"
+      description="Composed table surface for the canonical account grid."
+      headerActions={<Button variant="outline">Reset</Button>}
+      toolbar={
+        <ShowcaseToolbar
+          controller={controller}
+          label="Client mode"
+          primaryColumnId="account"
+          toggleColumnId="notes"
+          pinColumnId="owner"
+          sortColumnIds={['arr', 'renewalDate']}
+        />
+      }
+      loading={false}
+      emptyState={<div>No rows available.</div>}
+      footer={\`Page \${controller.pageIndex + 1} of \${controller.pageCount}\`}
+    />
+  );
+}`;
+
 export function LibrariesDesignSystemPage() {
 	return (
 		<div className="space-y-8">
@@ -52,65 +102,19 @@ export function LibrariesDesignSystemPage() {
 			</div>
 
 			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Example: App Layout</h2>
-				<CodeBlock
-					language="tsx"
-					code={`import { AppLayout } from '@contractspec/lib.design-system';
-import { AppSidebar } from '@contractspec/lib.design-system';
-
-export function Layout({ children }) {
-  return (
-    <AppLayout sidebar={<AppSidebar />}>
-      {children}
-    </AppLayout>
-  );
-}`}
-				/>
-			</div>
-
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Example: Zod Form</h2>
-				<CodeBlock
-					language="tsx"
-					code={`import { ZodForm } from '@contractspec/lib.design-system';
-import * as z from "zod";
-
-const schema = z.object({
-  name: z.string().min(1),
-  email: z.string().email(),
-});
-
-export function SignupForm() {
-  return (
-    <ZodForm
-      schema={schema}
-      onSubmit={(data) => console.log(data)}
-      submitLabel="Submit"
-    />
-  );
-}`}
-				/>
-			</div>
-
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">
-					Example: Code Block with Package Manager Tabs
-				</h2>
-				<CodeBlock
-					language="tsx"
-					code={`import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
-
-// For installation commands with package manager tabs
-<InstallCommand package="my-package" />
-<InstallCommand package={["react", "react-dom"]} dev />
-
-// For code examples with syntax highlighting
-<CodeBlock
-  language="typescript"
-  code={\`const hello = "world";\`}
-  filename="example.ts"
-/>`}
-				/>
+				<h2 className="font-bold text-2xl">Data table example</h2>
+				<p className="text-muted-foreground">
+					This is the composed lane from the canonical{' '}
+					<Link
+						href="/docs/examples/data-grid-showcase"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						Data Grid Showcase
+					</Link>
+					. The design-system wrapper owns title, description, header actions,
+					and the opinionated card shell on top of the raw web primitive.
+				</p>
+				<CodeBlock language="tsx" code={DESIGN_SYSTEM_TABLE_EXAMPLE} />
 			</div>
 
 			<div className="space-y-4">
@@ -127,6 +131,8 @@ export function SignupForm() {
 					<div className="card-subtle p-4">
 						<h3 className="mb-2 font-semibold">Data & Forms</h3>
 						<ul className="space-y-1 text-muted-foreground text-sm">
+							<li>DataTable</li>
+							<li>DataViewTable</li>
 							<li>DataViewRenderer</li>
 							<li>ZodForm</li>
 							<li>FormLayout, FormDialog</li>
@@ -151,8 +157,8 @@ export function SignupForm() {
 			</div>
 
 			<div className="flex items-center gap-4 pt-4">
-				<Link href="/docs/libraries/ui-kit" className="btn-ghost">
-					Previous: UI Kit
+				<Link href="/docs/libraries/ui-kit-web" className="btn-ghost">
+					Previous: UI Kit Web
 				</Link>
 				<Link href="/docs/libraries/accessibility" className="btn-primary">
 					Next: Accessibility <ChevronRight size={16} />

package/src/components/docs/libraries/LibrariesOverviewPage.tsx

@@ -36,10 +36,16 @@ const libraryGroups = [
 					'Render shared surfaces across web and React Native without forking the contract layer.',
 				href: '/docs/libraries/ui-kit',
 			},
+			{
+				title: '@contractspec/lib.ui-kit-web',
+				description:
+					'Use the raw web primitive layer directly when you want the browser table, accessibility, and interaction model without the design-system shell.',
+				href: '/docs/libraries/ui-kit-web',
+			},
 			{
 				title: '@contractspec/lib.design-system',
 				description:
-					'Build higher-level product surfaces and documented marketing/docs primitives on top of the UI kit.',
+					'Build higher-level product surfaces and documented marketing/docs primitives on top of the web and native UI packages.',
 				href: '/docs/libraries/design-system',
 			},
 			{

package/src/components/docs/libraries/LibrariesUIKitPage.tsx

@@ -2,6 +2,52 @@ import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const NATIVE_TABLE_EXAMPLE = `import { DataTable } from '@contractspec/lib.ui-kit/ui/data-table';
+import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
+
+import { SHOWCASE_ROWS } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.data';
+import { useShowcaseColumns } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.columns';
+import {
+  ExpandedRowContent,
+  ShowcaseToolbar,
+} from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.parts';
+
+export function NativeAccountGrid() {
+  const columns = useShowcaseColumns();
+
+  const controller = useContractTable({
+    data: SHOWCASE_ROWS,
+    columns,
+    selectionMode: 'single',
+    initialState: {
+      sorting: [{ id: 'arr', desc: true }],
+      pagination: { pageIndex: 0, pageSize: 4 },
+      columnVisibility: { notes: false },
+      columnPinning: { left: ['account'], right: [] },
+    },
+    renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
+    getCanExpand: () => true,
+  });
+
+  return (
+    <DataTable
+      controller={controller}
+      toolbar={
+        <ShowcaseToolbar
+          controller={controller}
+          label="Native primitive"
+          primaryColumnId="account"
+          toggleColumnId="notes"
+          pinColumnId="owner"
+          sortColumnIds={['arr', 'renewalDate']}
+        />
+      }
+      loading={false}
+      footer={\`Rows \${controller.rows.length}\`}
+    />
+  );
+}`;
+
 export function LibrariesUIKitPage() {
 	return (
 		<div className="space-y-8">
@@ -41,29 +87,21 @@ export function LibrariesUIKitPage() {
 			</div>
 
 			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Example Usage</h2>
-				<CodeBlock
-					language="tsx"
-					code={`import { Button } from '@contractspec/lib.ui-kit/ui/button';
-import { Text } from '@contractspec/lib.ui-kit/ui/text';
-import { Card, CardHeader, CardTitle, CardContent } from '@contractspec/lib.ui-kit/ui/card';
-
-export function MyComponent() {
-  return (
-    <Card className="w-full max-w-md">
-      <CardHeader>
-        <CardTitle>Welcome</CardTitle>
-      </CardHeader>
-      <CardContent className="gap-4">
-        <Text>This works on Web and Native.</Text>
-        <Button onPress={() => console.log('Clicked!')}>
-          Click me
-        </Button>
-      </CardContent>
-    </Card>
-  );
-}`}
-				/>
+				<h2 className="font-bold text-2xl">Data table example</h2>
+				<p className="text-muted-foreground">
+					The canonical{' '}
+					<Link
+						href="/docs/examples/data-grid-showcase"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						Data Grid Showcase
+					</Link>{' '}
+					uses <code>@contractspec/lib.ui-kit/ui/data-table</code> as the
+					native-first primitive lane. It shares the same controller model as
+					the web renderer while keeping the React Native / Expo surface
+					explicit.
+				</p>
+				<CodeBlock language="tsx" code={NATIVE_TABLE_EXAMPLE} />
 			</div>
 
 			<div className="space-y-4">
@@ -104,8 +142,8 @@ export function MyComponent() {
 				<Link href="/docs/libraries/schema" className="btn-ghost">
 					Previous: Schema
 				</Link>
-				<Link href="/docs/libraries/design-system" className="btn-primary">
-					Next: Design System <ChevronRight size={16} />
+				<Link href="/docs/libraries/ui-kit-web" className="btn-primary">
+					Next: UI Kit Web <ChevronRight size={16} />
 				</Link>
 			</div>
 		</div>

package/src/components/docs/libraries/LibrariesUIKitWebPage.tsx

@@ -0,0 +1,115 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+const WEB_PRIMITIVE_EXAMPLE = `import { DataTable } from '@contractspec/lib.ui-kit-web/ui/data-table';
+import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
+
+import { SHOWCASE_ROWS } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.data';
+import { useShowcaseColumns } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.columns';
+import {
+  ExpandedRowContent,
+  ShowcaseToolbar,
+} from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.parts';
+
+export function WebAccountGrid() {
+  const columns = useShowcaseColumns();
+
+  const controller = useContractTable({
+    data: SHOWCASE_ROWS,
+    columns,
+    selectionMode: 'single',
+    initialState: {
+      sorting: [{ id: 'lastActivityAt', desc: true }],
+      pagination: { pageIndex: 0, pageSize: 4 },
+      columnVisibility: { notes: false },
+      columnPinning: { left: ['account'], right: [] },
+    },
+    renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
+    getCanExpand: () => true,
+  });
+
+  return (
+    <DataTable
+      controller={controller}
+      toolbar={
+        <ShowcaseToolbar
+          controller={controller}
+          label="Web primitive"
+          primaryColumnId="account"
+          toggleColumnId="notes"
+          pinColumnId="owner"
+          sortColumnIds={['arr', 'renewalDate']}
+        />
+      }
+      loading={false}
+      emptyState={<div>No rows available.</div>}
+      footer={\`Rows \${controller.totalItems}\`}
+    />
+  );
+}`;
+
+export function LibrariesUIKitWebPage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">@contractspec/lib.ui-kit-web</h1>
+				<p className="text-muted-foreground">
+					Web-first React and Next primitives for ContractSpec. The canonical
+					data-table example uses this package to render the raw browser table
+					layer directly, without the design-system shell on top.
+				</p>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Installation</h2>
+				<InstallCommand package="@contractspec/lib.ui-kit-web" />
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Data table example</h2>
+				<p className="text-muted-foreground">
+					This is the raw browser lane from the canonical{' '}
+					<Link
+						href="/docs/examples/data-grid-showcase"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						Data Grid Showcase
+					</Link>
+					. It demonstrates the primitive renderer with sorting, pagination,
+					single selection, column visibility, column resizing, left/right
+					pinning, row expansion, loading, and empty-state slots.
+				</p>
+				<CodeBlock
+					language="tsx"
+					filename="web-account-grid.tsx"
+					code={WEB_PRIMITIVE_EXAMPLE}
+				/>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">What this layer owns</h2>
+				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
+					<li>The raw table renderer and browser interaction model.</li>
+					<li>
+						Pagination, column visibility menus, pin menus, resize handles, and
+						empty/loading states.
+					</li>
+					<li>
+						Accessibility helpers and other web-specific primitives that stay
+						outside the native-first package.
+					</li>
+				</ul>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/libraries/ui-kit" className="btn-ghost">
+					Previous: UI Kit
+				</Link>
+				<Link href="/docs/libraries/design-system" className="btn-primary">
+					Next: Design System <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
+}

package/src/components/docs/libraries/index.ts

@@ -23,5 +23,6 @@ export { LibrariesSLOPage } from './LibrariesSLOPage';
 export { LibrariesSupportBotPage } from './LibrariesSupportBotPage';
 export { LibrariesTestingPage } from './LibrariesTestingPage';
 export { LibrariesUIKitPage } from './LibrariesUIKitPage';
+export { LibrariesUIKitWebPage } from './LibrariesUIKitWebPage';
 export { LibrariesWorkflowComposerPage } from './LibrariesWorkflowComposerPage';
 export { LibrariesWorkflowsPage } from './LibrariesWorkflowsPage';

package/src/components/docs/specs/SpecsBuilderControlPlanePage.tsx

@@ -4,19 +4,20 @@ import Link from '@contractspec/lib.ui-link';
 const runtimeModes = [
 	{
 		title: 'Managed',
-		body: 'Best when the team wants the platform to own setup, routing, readiness, and mobile-safe defaults.',
+		body: 'Best when the team wants the platform to own setup, routing, readiness, API defaults, and mobile-safe operator flows.',
 	},
 	{
 		title: 'Local',
-		body: 'Best for power users who want tenant-local execution providers and tighter data-locality control.',
+		body: 'Best for power users who want local-daemon registration, tenant-local execution providers, and tighter data-locality control.',
 	},
 	{
 		title: 'Hybrid',
-		body: 'Best when some work should stay local while preview, review, or export flows still use managed coordination.',
+		body: 'Best when some work should stay local while preview, review, export, or mobile operator flows still use managed coordination.',
 	},
 ];
 
 const builderLoop = [
+	'Bootstrap managed, local-daemon, or hybrid presets explicitly instead of inventing provider posture ad hoc per host.',
 	'Capture prompts, files, voice, and other inbound sources into a typed workspace instead of relying on a single chat transcript.',
 	'Fuse the sources into decisions, assumptions, and blueprint updates with provenance and approval memory.',
 	'Compile authoring work into execution lanes, then route the work to explicit provider profiles and runtime targets.',
@@ -24,6 +25,12 @@ const builderLoop = [
 	'Keep mobile review parity so approvals, incidents, and patch proposals can be inspected away from the desktop workbench.',
 ];
 
+const operatorSignals = [
+	'local trust and lease posture for registered local runtimes',
+	'channel-action and comparison posture data in the shared Builder snapshot',
+	'preview, readiness, export, and mobile-review state derived from the same workspace snapshot',
+];
+
 export function SpecsBuilderControlPlanePage() {
 	return (
 		<div className="space-y-10">
@@ -151,6 +158,54 @@ Operate API proxy
 				</article>
 			</section>
 
+			<section className="editorial-panel space-y-5">
+				<div className="space-y-2">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						Workspace config carries the current Builder defaults
+					</h2>
+					<p className="text-muted-foreground text-sm leading-7">
+						Builder setup is no longer just an app-shell concern. The shared
+						workspace config now carries runtime mode, bootstrap preset, control
+						plane API defaults, and local runtime registration metadata so the
+						CLI, editors, and web shells resolve the same posture.
+					</p>
+				</div>
+				<CodeBlock
+					language="json"
+					filename=".contractsrc.json"
+					code={`{
+  "builder": {
+    "enabled": true,
+    "runtimeMode": "local",
+    "bootstrapPreset": "local_daemon_mvp",
+    "api": {
+      "baseUrl": "https://api.contractspec.io",
+      "controlPlaneTokenEnvVar": "CONTROL_PLANE_API_TOKEN"
+    },
+    "localRuntime": {
+      "runtimeId": "rt_local_daemon",
+      "grantedTo": "local:operator",
+      "providerIds": ["provider.codex", "provider.local.model"]
+    }
+  }
+}`}
+				/>
+			</section>
+
+			<section className="editorial-panel space-y-4">
+				<h2 className="font-serif text-3xl tracking-[-0.03em]">
+					Operator posture stays visible
+				</h2>
+				<ul className="editorial-list">
+					{operatorSignals.map((item) => (
+						<li key={item}>
+							<span className="editorial-list-marker" />
+							<span>{item}</span>
+						</li>
+					))}
+				</ul>
+			</section>
+
 			<section className="editorial-panel space-y-5">
 				<div className="space-y-2">
 					<h2 className="font-serif text-3xl tracking-[-0.03em]">

package/src/components/docs/specs/SpecsConnectPage.tsx

@@ -20,6 +20,12 @@ const artifacts = [
 	},
 ];
 
+const adoptionOutputs = [
+	'`.contractspec/adoption/catalog.json` mirrored from the bundled ContractSpec catalog',
+	'family-aware reuse recommendations for `ui`, `contracts`, `integrations`, `runtime`, `sharedLibs`, and `solutions`',
+	'verdict thresholds that can prefer workspace reuse, ContractSpec reuse, review, or explicit denial before a new implementation starts',
+];
+
 const adoptionSteps = [
 	'Enable `connect` in `.contractsrc.json` and keep your protected, immutable, generated, and smoke-check policies explicit.',
 	'Run `contractspec connect context` and `contractspec connect plan` before risky work so the agent is operating on task-scoped evidence, not ambient repo assumptions.',
@@ -81,6 +87,8 @@ export function SpecsConnectPage() {
 					language="bash"
 					filename="contractspec-connect"
 					code={`contractspec connect init --scope workspace
+contractspec connect adoption sync --json
+printf '{"goal":"Prefer an existing release helper before adding a new one"}' | contractspec connect adoption resolve --family sharedLibs --stdin --json
 contractspec connect context --task refactor-docs --paths packages/libs/contracts-spec/src/control-plane/contracts.ts --json
 printf '{"objective":"Document the control-plane contract surface","commands":["bun run typecheck"]}' | contractspec connect plan --task refactor-docs --stdin --json
 printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | contractspec connect verify --task refactor-docs --tool acp.fs.access --stdin --json
@@ -112,6 +120,28 @@ contractspec connect replay <decisionId> --json`}
 				</div>
 			</section>
 
+			<section className="editorial-panel space-y-5">
+				<div className="space-y-2">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						Reuse-first adoption is part of the workflow
+					</h2>
+					<p className="text-muted-foreground text-sm leading-7">
+						Connect adoption keeps reuse guidance in the same local control
+						surface. Before a new contract family, helper, or runtime
+						abstraction lands, Connect can mirror the bundled catalog and
+						resolve the best reuse candidate by family.
+					</p>
+				</div>
+				<ul className="editorial-list">
+					{adoptionOutputs.map((item) => (
+						<li key={item}>
+							<span className="editorial-list-marker" />
+							<span>{item}</span>
+						</li>
+					))}
+				</ul>
+			</section>
+
 			<section className="grid gap-5 lg:grid-cols-2">
 				<article className="editorial-panel space-y-4">
 					<h2 className="font-serif text-3xl tracking-[-0.03em]">