@contractspec/bundle.library 3.8.12 → 3.9.0

package/src/components/docs/generated/docs-index.workspace-cli.json

@@ -1,10 +1,10 @@
 [
-	{
-		"id": "workspace-cli/workspace-cli",
-		"title": "workspace-cli",
-		"summary": "Core CLI operations for managing ContractSpec workspaces\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: @lssm/core\n- **Tags**: cli, core\n- **File**: `packages/bundles/workspace/src/contracts/features/cli.feature.ts`",
-		"route": "/docs/reference/workspace-cli/workspace-cli",
-		"source": "generated",
-		"contentPath": "workspace-cli/workspace-cli.md"
-	}
-]
+  {
+    "id": "workspace-cli/workspace-cli",
+    "title": "workspace-cli",
+    "summary": "Core CLI operations for managing ContractSpec workspaces\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: @lssm/core\n- **Tags**: cli, core\n- **File**: `packages/bundles/workspace/src/contracts/features/cli.feature.ts`",
+    "route": "/docs/reference/workspace-cli/workspace-cli",
+    "source": "generated",
+    "contentPath": "workspace-cli/workspace-cli.md"
+  }
+]

package/src/components/docs/getting-started/CLIPage.tsx

@@ -4,6 +4,13 @@ import { ChevronRight } from 'lucide-react';
 
 export function CLIPage() {
 	const commands = [
+		{
+			name: 'onboard',
+			description:
+				'Primary OSS onboarding flow that recommends tracks, examples, and repo-local guides',
+			usage:
+				'contractspec onboard [track...] [--example <key>] [--dry-run] [--json]',
+		},
 		{
 			name: 'create',
 			description: 'Interactive wizard to create contract specifications',
@@ -73,16 +80,17 @@ export function CLIPage() {
 					<CodeBlock
 						language="bash"
 						code={`# Initialize project
+contractspec onboard
 bunx contractspec init
 
 # Create a spec
 contractspec create --type operation
 
 # Generate code
-contractspec build src/contracts/mySpec.ts
+contractspec generate
 
 # Validate
-contractspec validate src/contracts/mySpec.ts`}
+contractspec validate`}
 					/>
 				</div>
 

package/src/components/docs/getting-started/DataViewTutorialPage.tsx

@@ -2,6 +2,54 @@ import { CodeBlock } from '@contractspec/lib.design-system';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const DATAVIEW_TUTORIAL_EXAMPLE = `import { defineDataView } from '@contractspec/lib.contracts-spec/data-views';
+import { ListTransactions } from './list-transactions';
+
+export const TransactionHistory = defineDataView({
+  meta: {
+    key: 'billing.transactionHistory',
+    version: '1.0.0',
+    entity: 'transaction',
+    title: 'Transaction History',
+    description: 'Customer payment history',
+    domain: 'billing',
+    owners: ['team-billing'],
+    tags: ['payments'],
+    stability: 'stable',
+  },
+  source: {
+    primary: {
+      key: ListTransactions.meta.key,
+      version: ListTransactions.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 DataViewTutorialPage() {
 	return (
 		<div className="space-y-8">
@@ -46,77 +94,18 @@ export const ListTransactions = defineQuery({
 				<CodeBlock
 					language="typescript"
 					filename="lib/specs/billing/transaction-history.data-view.ts"
-					code={`import { defineDataView } from '@contractspec/lib.contracts-spec';
-import { ListTransactions } from './list-transactions';
-
-export const TransactionHistory = defineDataView({
-  meta: {
-    key: 'billing.transactionHistory',
-    version: '1.0.0',
-    entity: 'transaction',
-    description: 'Customer payment history',
-    goal: 'Help customers track spending',
-    context: 'Account dashboard',
-    owners: ['team-billing'],
-    stability: 'stable',
-    tags: ['payments'],
-  },
-  source: {
-    primary: ListTransactions,
-  },
-  view: {
-    kind: 'list',
-    fields: [
-      {
-        key: 'date',
-        label: 'Date',
-        dataPath: 'createdAt',
-        format: 'date',
-        sortable: true
-      },
-      {
-        key: 'description',
-        label: 'Description',
-        dataPath: 'description'
-      },
-      {
-        key: 'amount',
-        label: 'Amount',
-        dataPath: 'amount',
-        format: 'currency',
-        sortable: true
-      },
-      {
-        key: 'status',
-        label: 'Status',
-        dataPath: 'status',
-        format: 'badge'
-      },
-    ],
-    filters: [
-      {
-        key: 'status',
-        label: 'Status',
-        field: 'status',
-        type: 'enum',
-        options: [
-          { value: 'succeeded', label: 'Paid' },
-          { value: 'pending', label: 'Pending' },
-          { value: 'failed', label: 'Failed' },
-        ],
-      },
-      {
-        key: 'dateRange',
-        label: 'Date Range',
-        field: 'createdAt',
-        type: 'dateRange',
-      },
-    ],
-    defaultSort: { field: 'date', direction: 'desc' },
-    pagination: { pageSize: 25 },
-  },
-});`}
+					code={DATAVIEW_TUTORIAL_EXAMPLE}
 				/>
+				<p className="text-muted-foreground text-sm">
+					The live version of this pattern is available in the canonical{' '}
+					<Link
+						href="/docs/examples/data-grid-showcase"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						Data Grid Showcase
+					</Link>
+					.
+				</p>
 			</div>
 
 			<div className="space-y-4">
@@ -161,6 +150,10 @@ export function TransactionsPage() {
 				<ul className="space-y-2 text-muted-foreground text-sm">
 					<li>Same spec renders on web (React) and mobile (React Native)</li>
 					<li>Filters, sorting, and pagination handled automatically</li>
+					<li>
+						Column visibility, pinning, resizing, and row expansion stay
+						contract-driven
+					</li>
 					<li>Format rules (currency, dates, badges) applied consistently</li>
 					<li>Export to CSV/PDF using the same spec</li>
 					<li>A/B test different layouts without touching the backend</li>

package/src/components/docs/getting-started/StartHerePage.tsx

@@ -19,12 +19,13 @@ export function StartHerePage() {
 				</div>
 
 				<div className="space-y-3">
-					<h2 className="font-bold text-2xl">Add core libraries</h2>
-					<InstallCommand
-						package={[
-							'@contractspec/lib.contracts-spec',
-							'@contractspec/lib.schema',
-						]}
+					<h2 className="font-bold text-2xl">Generate repo-local guidance</h2>
+					<CodeBlock
+						language="bash"
+						filename="start-here-onboard"
+						code={`contractspec onboard
+# optional focused track
+contractspec onboard knowledge --example knowledge-canon`}
 					/>
 				</div>
 
@@ -38,7 +39,7 @@ export function StartHerePage() {
 				</div>
 
 				<div className="space-y-3">
-					<h2 className="font-bold text-2xl">Create your first contract</h2>
+					<h2 className="font-bold text-2xl">Author your first contract</h2>
 					<CodeBlock
 						language="bash"
 						filename="start-here-create"
@@ -51,8 +52,8 @@ export function StartHerePage() {
 					<CodeBlock
 						language="bash"
 						filename="start-here-build"
-						code={`contractspec build src/contracts/mySpec.ts
-contractspec validate src/contracts/mySpec.ts`}
+						code={`contractspec generate
+contractspec validate`}
 					/>
 				</div>
 			</div>

package/src/components/docs/guides/GuideConnectInRepoPage.tsx

@@ -8,6 +8,8 @@ const artifactPaths = [
 	'.contractspec/connect/patch-verdict.json',
 	'.contractspec/connect/audit.ndjson',
 	'.contractspec/connect/decisions/<decisionId>/',
+	'.contractspec/adoption/catalog.json',
+	'.contractspec/adoption/overrides.json',
 ];
 
 export function GuideConnectInRepoPage() {
@@ -26,6 +28,7 @@ export function GuideConnectInRepoPage() {
 				<h2 className="font-bold text-2xl">What you&apos;ll build</h2>
 				<ul className="space-y-2 text-muted-foreground text-sm">
 					<li>A workspace-level Connect config in `.contractsrc.json`.</li>
+					<li>A reuse-first adoption check before new implementation work.</li>
 					<li>A context and plan flow for one task.</li>
 					<li>
 						Verified file and shell mutations with local review/replay evidence.
@@ -69,6 +72,28 @@ export function GuideConnectInRepoPage() {
       "allow": ["bun run typecheck"],
       "review": ["git push"],
       "deny": ["git reset --hard", "git push --force", "rm -rf"]
+    },
+    "adoption": {
+      "enabled": true,
+      "catalog": {
+        "indexPath": ".contractspec/adoption/catalog.json",
+        "overrideManifestPath": ".contractspec/adoption/overrides.json"
+      },
+      "workspaceScan": {
+        "include": ["packages/**", "docs/**"],
+        "exclude": ["generated/**", "dist/**"]
+      },
+      "families": {
+        "contracts": true,
+        "runtime": true,
+        "sharedLibs": true
+      },
+      "thresholds": {
+        "workspaceReuse": "permit",
+        "contractspecReuse": "permit",
+        "ambiguous": "require_review",
+        "newImplementation": "require_review"
+      }
     }
   }
 }`}
@@ -94,7 +119,31 @@ export function GuideConnectInRepoPage() {
 
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">
-						3) Project context and compile a plan
+						3) Mirror the adoption catalog and resolve reuse first
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						Connect adoption is the reuse-first layer for authoring. Mirror the
+						local catalog, then resolve the best existing surface for the family
+						you are about to touch before you scaffold or invent anything new.
+					</p>
+					<CodeBlock
+						language="bash"
+						filename="connect-adoption"
+						code={`contractspec connect adoption sync --json
+
+printf '{"goal":"Prefer an existing release helper before adding a new one"}' | \\
+  contractspec connect adoption resolve --family sharedLibs --stdin --json`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: a mirrored local adoption catalog plus a reuse
+						recommendation that can point to an existing workspace package or a
+						ContractSpec surface before the task reaches file mutation.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						4) Project context and compile a plan
 					</h2>
 					<p className="text-muted-foreground text-sm">
 						Use the task id as the thread that connects context, plan, verdict,
@@ -120,7 +169,7 @@ printf '{"objective":"Document the control-plane contract surface","commands":["
 
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">
-						4) Verify file and shell mutations
+						5) Verify file and shell mutations
 					</h2>
 					<CodeBlock
 						language="bash"
@@ -151,7 +200,7 @@ printf 'bun run typecheck' | \\
 
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">
-						5) Review, replay, and optional Studio sync
+						6) Review, replay, and optional Studio sync
 					</h2>
 					<CodeBlock
 						language="bash"

package/src/components/docs/guides/GuideHostBuilderWorkbenchPage.tsx

@@ -13,6 +13,13 @@ const builderCommands = [
 	'builder.export.approve',
 	'builder.export.execute',
 ];
+
+const operatorStatusDetails = [
+	'local runtime trust and lease details',
+	'channel-action posture for mobile/operator follow-up',
+	'comparison posture and export readiness from the shared snapshot',
+];
+
 export function GuideHostBuilderWorkbenchPage() {
 	return (
 		<div className="space-y-8">
@@ -68,8 +75,9 @@ export function GuideHostBuilderWorkbenchPage() {
 					/>
 					<p className="text-muted-foreground text-sm">
 						Expected output: one `BuilderWorkspaceSnapshot` containing
-						workspace, plan, providers, runtime targets, preview, export, and
-						mobile review state.
+						workspace, plan, providers, runtime targets, preview, export, mobile
+						review state, and the operator posture needed for local trust,
+						lease, and comparison status.
 					</p>
 				</div>
 				<div className="space-y-3">
@@ -124,7 +132,38 @@ async function runAction(commandKey: string, payload?: Record<string, unknown>)
 				</div>
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">
-						3) Bootstrap providers and routing policy explicitly
+						3) Persist Builder defaults in workspace config
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						The host should agree with the CLI and setup flows on the same
+						control-plane defaults. For local or hybrid setups, keep the Builder
+						API base URL, token env var, and local runtime metadata in
+						`.contractsrc.json`.
+					</p>
+					<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"]
+    }
+  }
+}`}
+					/>
+				</div>
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						4) Bootstrap providers and routing policy explicitly
 					</h2>
 					<p className="text-muted-foreground text-sm">
 						Builder v3 treats provider routing as policy, not heuristic. Use the
@@ -154,8 +193,18 @@ async function runAction(commandKey: string, payload?: Record<string, unknown>)
 						))}
 					</ul>
 				</div>
+				<div className="card-subtle space-y-3 p-6">
+					<h3 className="font-semibold text-lg">
+						Snapshot-backed operator details
+					</h3>
+					<ul className="space-y-2 text-muted-foreground text-sm">
+						{operatorStatusDetails.map((detail) => (
+							<li key={detail}>{detail}</li>
+						))}
+					</ul>
+				</div>
 				<div className="space-y-3">
-					<h2 className="font-bold text-2xl">4) Keep runtime mode explicit</h2>
+					<h2 className="font-bold text-2xl">5) Keep runtime mode explicit</h2>
 					<p className="text-muted-foreground text-sm">
 						Preview and export flows are runtime-mode aware. The host chooses
 						between `managed`, `local`, and `hybrid` and passes that choice into
@@ -178,7 +227,7 @@ await executeBuilderCommand({
 					/>
 				</div>
 				<div className="space-y-3">
-					<h2 className="font-bold text-2xl">5) Link mobile review flows</h2>
+					<h2 className="font-bold text-2xl">6) Link mobile review flows</h2>
 					<p className="text-muted-foreground text-sm">
 						When a patch proposal, approval ticket, or incident needs operator
 						follow-up away from the desktop workbench, deep-link into the mobile
@@ -201,7 +250,7 @@ await executeBuilderCommand({
 				</div>
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">
-						6) Keep Connect adjacent, not embedded
+						7) Keep Connect adjacent, not embedded
 					</h2>
 					<p className="text-muted-foreground text-sm">
 						Builder owns the authoring control plane. When Builder delegates

package/src/components/docs/guides/GuideReleaseCapsulesPage.tsx

@@ -0,0 +1,147 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+const docSyncTargets = [
+	'root `README.md` and generated root `AGENTS.md` inputs when contributor or operator workflow changes',
+	'the nearest package `README.md` and `AGENTS.md` for any touched public package surface',
+	'website docs and `/llms*` summaries when the release changes how users or contributors should work',
+];
+
+export function GuideReleaseCapsulesPage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-3">
+				<h1 className="font-bold text-4xl">Author release capsules</h1>
+				<p className="text-lg text-muted-foreground">
+					Pair each publishable changeset with a structured release capsule so
+					changelog, upgrade, and docs surfaces all read from the same release
+					source of truth.
+				</p>
+			</div>
+
+			<div className="card-subtle space-y-4 p-6">
+				<h2 className="font-bold text-2xl">What you&apos;ll build</h2>
+				<ul className="space-y-2 text-muted-foreground text-sm">
+					<li>
+						A <code>.changeset/&lt;slug&gt;.md</code> file for package/version
+						intent.
+					</li>
+					<li>
+						A <code>.changeset/&lt;slug&gt;.release.yaml</code> companion for
+						audiences, migrations, validation, and evidence.
+					</li>
+					<li>
+						Generated release artifacts that the website changelog and upgrade
+						flows can consume safely.
+					</li>
+				</ul>
+			</div>
+
+			<div className="space-y-6">
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						1) Create the paired changeset files
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						The Markdown file states the package bumps and reader-facing change
+						intent. The YAML file carries the structured release metadata.
+					</p>
+					<CodeBlock
+						language="yaml"
+						filename=".changeset/contract-dx-first-slice.release.yaml"
+						code={`schemaVersion: "1"
+slug: contract-dx-first-slice
+summary: Improve app-config, theme, and feature authoring with explicit validation and shared setup alignment.
+isBreaking: false
+packages:
+  - name: "@contractspec/lib.contracts-spec"
+    releaseType: minor
+validation:
+  commands:
+    - "cd packages/libs/contracts-spec && bun run test && bun run typecheck"
+  evidence:
+    - "Package-level validation entrypoints now back setup, docs, and CLI authoring flows."`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: every publishable slug has both the human-facing
+						changeset and the structured release capsule beside it.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						2) Use the release authoring commands instead of raw drift-prone
+						edits
+					</h2>
+					<CodeBlock
+						language="bash"
+						filename="release-authoring"
+						code={`contractspec release init --summary "Improve app-config, theme, and feature authoring"
+
+# Or revise an existing capsule with the guided flow
+contractspec release edit contract-dx-first-slice`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: the CLI scaffolds or revises the paired files with
+						the current release schema instead of leaving maintainers to
+						hand-roll YAML structure.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						3) Build the generated release artifacts before consuming them
+					</h2>
+					<CodeBlock
+						language="bash"
+						filename="release-build"
+						code={`contractspec release build`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: `generated/releases/manifest.json`,
+						`generated/releases/upgrade-manifest.json`, and the related
+						customer/maintainer guidance files are refreshed from the release
+						capsules.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						4) Enforce completeness before publishing or building the changelog
+					</h2>
+					<CodeBlock
+						language="bash"
+						filename="release-check"
+						code={`contractspec release check --strict`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: missing capsules, incomplete migration guidance, or
+						stale generated release artifacts are flagged before the website
+						changelog or publish workflow treats the release data as canonical.
+					</p>
+				</div>
+
+				<div className="card-subtle space-y-3 p-6">
+					<h3 className="font-semibold text-lg">
+						5) Sync the public docs if workflow expectations changed
+					</h3>
+					<ul className="space-y-2 text-muted-foreground text-sm">
+						{docSyncTargets.map((target) => (
+							<li key={target}>{target}</li>
+						))}
+					</ul>
+				</div>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/guides/connect-in-a-repo" className="btn-primary">
+					Connect guide <ChevronRight size={16} />
+				</Link>
+				<Link href="/changelog" className="btn-ghost">
+					Website changelog
+				</Link>
+			</div>
+		</div>
+	);
+}

package/src/components/docs/guides/GuidesIndexPage.tsx

@@ -59,6 +59,13 @@ const guides = [
 		href: '/docs/guides/connect-in-a-repo',
 		time: '15 min',
 	},
+	{
+		title: 'Author release capsules',
+		description:
+			'Pair changesets with structured release capsules and generate the artifacts that changelog and upgrade flows consume.',
+		href: '/docs/guides/release-capsules',
+		time: '15 min',
+	},
 	{
 		title: 'CI diff gating',
 		description:

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

@@ -9,5 +9,6 @@ export { GuideGenerateDocsClientsSchemasPage } from './GuideGenerateDocsClientsS
 export { GuideHostBuilderWorkbenchPage } from './GuideHostBuilderWorkbenchPage';
 export { GuideImportExistingCodebasesPage } from './GuideImportExistingCodebasesPage';
 export { GuideNextjsOneEndpointPage } from './GuideNextjsOneEndpointPage';
+export { GuideReleaseCapsulesPage } from './GuideReleaseCapsulesPage';
 export { GuideSpecValidationTypingPage } from './GuideSpecValidationTypingPage';
 export { GuidesIndexPage } from './GuidesIndexPage';