@contractspec/bundle.library 3.8.10 → 3.8.12

package/src/components/docs/DocsIndexPage.tsx

@@ -27,6 +27,27 @@ const proofPoints = [
 	},
 ];
 
+const implementedSpecPacks = [
+	{
+		title: 'ContractSpec Connect',
+		body: 'Guard coding-agent edits and commands with local-first context, plan packets, patch verdicts, and review packets.',
+		specHref: '/docs/specs/connect',
+		guideHref: '/docs/guides/connect-in-a-repo',
+	},
+	{
+		title: 'Module bundles',
+		body: 'Define AI-native surfaces as typed bundle specs that resolve into auditable runtime plans.',
+		specHref: '/docs/specs/module-bundles',
+		guideHref: '/docs/guides/first-module-bundle',
+	},
+	{
+		title: 'Builder control plane',
+		body: 'Coordinate multimodal authoring, provider routing, readiness, export, and mobile review through governed contracts.',
+		specHref: '/docs/specs/builder-control-plane',
+		guideHref: '/docs/guides/host-builder-workbench',
+	},
+];
+
 export function DocsIndexPage() {
 	const sections = getDocsHomeSections();
 	const secondary = getSecondaryDocsPages().slice(0, 6);
@@ -74,6 +95,40 @@ export function DocsIndexPage() {
 				})}
 			</section>
 
+			<section className="space-y-5">
+				<div className="space-y-2">
+					<p className="editorial-kicker">Implemented packs</p>
+					<h2 className="editorial-panel-title">
+						Use the three higher-order systems that are already wired
+					</h2>
+					<p className="editorial-copy text-sm">
+						These pages are the canonical landing points for agent enforcement,
+						AI-native surface composition, and Builder authoring. Each one now
+						has a matching practical guide.
+					</p>
+				</div>
+				<div className="grid gap-4 lg:grid-cols-3">
+					{implementedSpecPacks.map((item) => (
+						<article key={item.title} className="editorial-panel space-y-4">
+							<div>
+								<h3 className="font-semibold text-xl">{item.title}</h3>
+								<p className="mt-2 text-muted-foreground text-sm leading-7">
+									{item.body}
+								</p>
+							</div>
+							<div className="flex flex-wrap gap-3">
+								<Link href={item.specHref} className="btn-primary text-sm">
+									Open spec page <ArrowRight size={16} />
+								</Link>
+								<Link href={item.guideHref} className="btn-ghost text-sm">
+									Read practical guide
+								</Link>
+							</div>
+						</article>
+					))}
+				</div>
+			</section>
+
 			<section className="editorial-panel space-y-5">
 				<div className="space-y-2">
 					<p className="editorial-kicker">Quick start</p>

package/src/components/docs/architecture/ArchitectureControlPlanePage.tsx

@@ -94,6 +94,25 @@ Capabilities
 				</ul>
 			</div>
 
+			<section className="editorial-panel space-y-4">
+				<h2 className="font-serif text-3xl tracking-[-0.03em]">
+					Apply the runtime locally with Connect
+				</h2>
+				<p className="text-muted-foreground text-sm leading-7">
+					The control plane defines the governance contracts. Connect is the
+					local adapter that turns those contracts into task-scoped context,
+					plan, verification, review, and replay flows for coding agents.
+				</p>
+				<div className="flex flex-wrap gap-3">
+					<Link href="/docs/specs/connect" className="btn-primary">
+						Connect spec
+					</Link>
+					<Link href="/docs/guides/connect-in-a-repo" className="btn-ghost">
+						Use Connect in a repo
+					</Link>
+				</div>
+			</section>
+
 			<div className="space-y-4">
 				<h2 className="font-bold text-2xl">Implementation map</h2>
 				<CodeBlock

package/src/components/docs/architecture/ArchitectureOverviewPage.tsx

@@ -47,6 +47,40 @@ export function ArchitectureOverviewPage() {
 				))}
 			</div>
 
+			<section className="editorial-panel space-y-5">
+				<div className="space-y-2">
+					<h2 className="font-serif text-3xl tracking-[-0.03em]">
+						UI composition belongs in the bundle runtime layer
+					</h2>
+					<p className="text-muted-foreground text-sm leading-7">
+						When the system needs adaptive layouts, entity workbenches,
+						assistant slots, and safe overlays, use module bundles as the layer
+						between the contract model and the rendered surface.
+					</p>
+				</div>
+				<div className="grid gap-4 md:grid-cols-2">
+					<Link href="/docs/specs/module-bundles" className="docs-footer-link">
+						<h3 className="font-semibold text-lg">Module bundles spec</h3>
+						<p className="text-muted-foreground text-sm leading-7">
+							See the typed bundle contract, resolved surface plan model, and
+							bounded AI/runtime behavior.
+						</p>
+					</Link>
+					<Link
+						href="/docs/guides/first-module-bundle"
+						className="docs-footer-link"
+					>
+						<h3 className="font-semibold text-lg">
+							Build a first module bundle
+						</h3>
+						<p className="text-muted-foreground text-sm leading-7">
+							Follow the route-to-plan-to-render path with one practical host
+							example.
+						</p>
+					</Link>
+				</div>
+			</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/docsManifest.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'bun:test';
+import { getDocsPageByHref, getPrimaryDocsSections } from './docsManifest';
+
+const NON_MANIFEST_DOC_ROUTES = new Set(['/docs/architecture/control-plane']);
+
+describe('docs manifest learning paths', () => {
+	it('registers the canonical spec-pack pages', () => {
+		for (const href of [
+			'/docs/specs/connect',
+			'/docs/specs/module-bundles',
+			'/docs/specs/builder-control-plane',
+		]) {
+			expect(getDocsPageByHref(href)).toBeDefined();
+		}
+	});
+
+	it('registers the practical guides in the build section', () => {
+		const buildSection = getPrimaryDocsSections().find(
+			(section) => section.key === 'build'
+		);
+
+		expect(buildSection).toBeDefined();
+
+		const buildHrefs = buildSection?.items.map((item) => item.href) ?? [];
+
+		expect(buildHrefs).toContain('/docs/guides/connect-in-a-repo');
+		expect(buildHrefs).toContain('/docs/guides/first-module-bundle');
+		expect(buildHrefs).toContain('/docs/guides/host-builder-workbench');
+	});
+
+	it('orders the new guides as intended within build traversal', () => {
+		const buildSection = getPrimaryDocsSections().find(
+			(section) => section.key === 'build'
+		);
+		const buildHrefs = buildSection?.items.map((item) => item.href) ?? [];
+
+		expect(
+			buildHrefs.indexOf('/docs/guides/first-module-bundle')
+		).toBeGreaterThan(
+			buildHrefs.indexOf('/docs/guides/docs-generation-pipeline')
+		);
+		expect(
+			buildHrefs.indexOf('/docs/guides/host-builder-workbench')
+		).toBeGreaterThan(buildHrefs.indexOf('/docs/guides/first-module-bundle'));
+		expect(
+			buildHrefs.indexOf('/docs/guides/connect-in-a-repo')
+		).toBeGreaterThan(
+			buildHrefs.indexOf('/docs/guides/host-builder-workbench')
+		);
+	});
+
+	it('keeps related-page doc links pointed at valid docs routes', () => {
+		for (const href of [
+			'/docs/specs/connect',
+			'/docs/guides/connect-in-a-repo',
+			'/docs/specs/module-bundles',
+			'/docs/guides/first-module-bundle',
+			'/docs/specs/builder-control-plane',
+			'/docs/guides/host-builder-workbench',
+			'/docs/architecture',
+			'/docs/architecture/control-plane',
+			'/docs/specs/overlays',
+			'/docs/studio',
+		]) {
+			expect(
+				getDocsPageByHref(href) != null || NON_MANIFEST_DOC_ROUTES.has(href)
+			).toBe(true);
+		}
+	});
+});

package/src/components/docs/docsManifest.ts

@@ -221,13 +221,47 @@ export const DOCS_PAGES: readonly DocsPageEntry[] = [
 		audience: 'oss',
 		ctaMode: 'oss-next',
 	},
+	{
+		href: '/docs/specs/module-bundles',
+		title: 'Module bundles',
+		description:
+			'Define AI-native surfaces as typed bundle specs that resolve into personalized, auditable runtime plans.',
+		section: 'core-model',
+		order: 70,
+		primaryNav: true,
+		audience: 'oss',
+		ctaMode: 'oss-next',
+	},
+	{
+		href: '/docs/specs/connect',
+		title: 'ContractSpec Connect',
+		description:
+			'Guard coding-agent edits and shell actions with task-scoped context, plan packets, patch verdicts, and review packets.',
+		section: 'core-model',
+		order: 80,
+		navTitle: 'Connect',
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'oss-next',
+	},
+	{
+		href: '/docs/specs/builder-control-plane',
+		title: 'Builder control plane',
+		description:
+			'Route multimodal authoring work through governed builder contracts, provider policies, readiness gates, and mobile review flows.',
+		section: 'core-model',
+		order: 90,
+		primaryNav: true,
+		audience: 'studio-bridge',
+		ctaMode: 'studio-bridge',
+	},
 	{
 		href: '/docs/guides/contract-types',
 		title: 'Contract types',
 		description:
 			'Choose the right contract surface for the behavior you want to make explicit.',
 		section: 'core-model',
-		order: 70,
+		order: 100,
 		primaryNav: true,
 		audience: 'oss',
 		ctaMode: 'oss-next',
@@ -303,6 +337,42 @@ export const DOCS_PAGES: readonly DocsPageEntry[] = [
 		audience: 'oss',
 		ctaMode: 'reference',
 	},
+	{
+		href: '/docs/guides/first-module-bundle',
+		title: 'Build a first module bundle',
+		description:
+			'Define one bundle spec, resolve a personalized surface plan, and render it through the React host layer.',
+		section: 'build',
+		order: 65,
+		navTitle: 'First module bundle',
+		primaryNav: true,
+		audience: 'oss',
+		ctaMode: 'oss-next',
+	},
+	{
+		href: '/docs/guides/host-builder-workbench',
+		title: 'Host the Builder workbench',
+		description:
+			'Load a Builder workspace snapshot, wire common commands, and keep runtime mode plus mobile review flows explicit.',
+		section: 'build',
+		order: 66,
+		navTitle: 'Host Builder workbench',
+		primaryNav: true,
+		audience: 'studio-bridge',
+		ctaMode: 'studio-bridge',
+	},
+	{
+		href: '/docs/guides/connect-in-a-repo',
+		title: 'Use Connect in a repo',
+		description:
+			'Enable Connect in workspace config, verify agent actions, and inspect local review and replay artifacts.',
+		section: 'build',
+		order: 67,
+		navTitle: 'Connect in a repo',
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'oss-next',
+	},
 	{
 		href: '/docs/libraries',
 		title: 'Libraries overview',

package/src/components/docs/ecosystem/PluginsPage.tsx

@@ -39,54 +39,68 @@ export function EcosystemPluginsPage() {
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">Where plugin sources live</h2>
 					<p className="text-muted-foreground text-sm">
-						Marketplace plugin sources are kept in a dedicated package so they
-						can evolve with the monorepo safely.
+						Marketplace plugin artifacts are kept in a dedicated package, while
+						the canonical reusable source lives in agentpacks under `packs/`.
 					</p>
 					<CodeBlock
 						language="text"
 						filename="catalog-layout"
 						code={`packages/apps-registry/cursor-marketplace/
+  .cursor-plugin/marketplace.json
   plugins/
     contractspec/
     contractspec-contracts-spec/
     contractspec-contracts-integrations/
-    contractspec-ai-agent/`}
+    contractspec-ai-agent/
+
+packs/
+  contractspec-contracts-spec/`}
 					/>
 				</div>
 
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">Root marketplace manifest</h2>
 					<p className="text-muted-foreground text-sm">
-						Cursor submission reads <code>.cursor-plugin/marketplace.json</code>{' '}
-						at repository root and resolves each plugin source path.
+						Cursor submission reads the catalog manifest inside the marketplace
+						package and resolves plugin paths relative to that package.
 					</p>
 					<CodeBlock
 						language="json"
-						filename=".cursor-plugin/marketplace.json"
+						filename="packages/apps-registry/cursor-marketplace/.cursor-plugin/marketplace.json"
 						code={`{
   "name": "contractspec-marketplace",
+  "owner": { "name": "ContractSpec Team" },
   "plugins": [
     {
       "name": "contractspec",
-      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec"
+      "source": "plugins/contractspec"
     },
     {
       "name": "contractspec-contracts-spec",
-      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-contracts-spec"
+      "source": "plugins/contractspec-contracts-spec"
     },
     {
       "name": "contractspec-contracts-integrations",
-      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-contracts-integrations"
+      "source": "plugins/contractspec-contracts-integrations"
     },
     {
       "name": "contractspec-ai-agent",
-      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-ai-agent"
+      "source": "plugins/contractspec-ai-agent"
     }
   ]
 }`}
 					/>
 				</div>
 
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">Generated multi-host system</h2>
+					<p className="text-muted-foreground text-sm">
+						The Cursor plugin is publishable metadata only. Customer-facing
+						Cursor, Claude Code, and Codex outputs are generated from the same
+						pack source with hook and MCP delivery.
+					</p>
+				</div>
+
 				<div className="space-y-3">
 					<h2 className="font-bold text-2xl">Validation gate</h2>
 					<p className="text-muted-foreground text-sm">

package/src/components/docs/ecosystem/RegistryPage.tsx

@@ -16,22 +16,26 @@ export function EcosystemRegistryPage() {
 			<div className="card-subtle space-y-4 p-6">
 				<h2 className="font-bold text-2xl">Root manifest shape</h2>
 				<p className="text-muted-foreground text-sm">
-					Cursor reads <code>.cursor-plugin/marketplace.json</code> at
-					repository root and resolves each plugin source path.
+					Cursor reads{' '}
+					<code>
+						packages/apps-registry/cursor-marketplace/.cursor-plugin/marketplace.json
+					</code>{' '}
+					for the catalog and resolves each plugin source path from there.
 				</p>
 				<CodeBlock
 					language="json"
-					filename=".cursor-plugin/marketplace.json"
+					filename="packages/apps-registry/cursor-marketplace/.cursor-plugin/marketplace.json"
 					code={`{
   "name": "contractspec-marketplace",
+  "owner": { "name": "ContractSpec Team" },
   "plugins": [
     {
       "name": "contractspec",
-      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec"
+      "source": "plugins/contractspec"
     },
     {
       "name": "contractspec-contracts-spec",
-      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-contracts-spec"
+      "source": "plugins/contractspec-contracts-spec"
     }
   ]
 }`}
@@ -42,7 +46,8 @@ export function EcosystemRegistryPage() {
 				<h2 className="font-bold text-2xl">Per-plugin contract</h2>
 				<p className="text-muted-foreground text-sm">
 					Each plugin source must include a Cursor plugin manifest and
-					composable assets.
+					composable assets. The publishable plugin is derived from a reusable
+					pack and then validated here.
 				</p>
 				<CodeBlock
 					language="text"