@contractspec/bundle.library 3.8.12 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/bundle.library",
-  "version": "3.8.12",
+  "version": "3.9.0",
   "type": "module",
   "scripts": {
     "clean": "rm -rf dist",
@@ -48,6 +48,12 @@
       "node": "./dist/node/application/mcp/cliMcp.js",
       "default": "./dist/application/mcp/cliMcp.js"
     },
+    "./application/mcp/cliMcp.onboarding": {
+      "types": "./dist/application/mcp/cliMcp.onboarding.d.ts",
+      "bun": "./dist/application/mcp/cliMcp.onboarding.js",
+      "node": "./dist/node/application/mcp/cliMcp.onboarding.js",
+      "default": "./dist/application/mcp/cliMcp.onboarding.js"
+    },
     "./application/mcp/common": {
       "types": "./dist/application/mcp/common.d.ts",
       "bun": "./dist/application/mcp/common.js",
@@ -60,6 +66,12 @@
       "node": "./dist/node/application/mcp/contractsMcp.js",
       "default": "./dist/application/mcp/contractsMcp.js"
     },
+    "./application/mcp/contractsMcpAdoptionTools": {
+      "types": "./dist/application/mcp/contractsMcpAdoptionTools.d.ts",
+      "bun": "./dist/application/mcp/contractsMcpAdoptionTools.js",
+      "node": "./dist/node/application/mcp/contractsMcpAdoptionTools.js",
+      "default": "./dist/application/mcp/contractsMcpAdoptionTools.js"
+    },
     "./application/mcp/contractsMcpResources": {
       "types": "./dist/application/mcp/contractsMcpResources.d.ts",
       "bun": "./dist/application/mcp/contractsMcpResources.js",
@@ -498,6 +510,12 @@
       "node": "./dist/node/components/docs/guides/GuideNextjsOneEndpointPage.js",
       "default": "./dist/components/docs/guides/GuideNextjsOneEndpointPage.js"
     },
+    "./components/docs/guides/GuideReleaseCapsulesPage": {
+      "types": "./dist/components/docs/guides/GuideReleaseCapsulesPage.d.ts",
+      "bun": "./dist/components/docs/guides/GuideReleaseCapsulesPage.js",
+      "node": "./dist/node/components/docs/guides/GuideReleaseCapsulesPage.js",
+      "default": "./dist/components/docs/guides/GuideReleaseCapsulesPage.js"
+    },
     "./components/docs/guides/guides.docblocks": {
       "types": "./dist/components/docs/guides/guides.docblocks.d.ts",
       "bun": "./dist/components/docs/guides/guides.docblocks.js",
@@ -882,6 +900,12 @@
       "node": "./dist/node/components/docs/libraries/LibrariesUIKitPage.js",
       "default": "./dist/components/docs/libraries/LibrariesUIKitPage.js"
     },
+    "./components/docs/libraries/LibrariesUIKitWebPage": {
+      "types": "./dist/components/docs/libraries/LibrariesUIKitWebPage.d.ts",
+      "bun": "./dist/components/docs/libraries/LibrariesUIKitWebPage.js",
+      "node": "./dist/node/components/docs/libraries/LibrariesUIKitWebPage.js",
+      "default": "./dist/components/docs/libraries/LibrariesUIKitWebPage.js"
+    },
     "./components/docs/libraries/LibrariesWorkflowComposerPage": {
       "types": "./dist/components/docs/libraries/LibrariesWorkflowComposerPage.d.ts",
       "bun": "./dist/components/docs/libraries/LibrariesWorkflowComposerPage.js",
@@ -1902,25 +1926,26 @@
     "react": "19.2.0"
   },
   "dependencies": {
+    "@contractspec/bundle.workspace": "4.5.0",
     "@apollo/client": "^4.1.7",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@contractspec/lib.ai-providers": "3.7.13",
-    "@contractspec/lib.contracts-spec": "5.3.0",
-    "@contractspec/lib.contracts-library": "3.7.19",
-    "@contractspec/lib.content-gen": "3.7.19",
-    "@contractspec/lib.contracts-runtime-server-mcp": "3.7.19",
-    "@contractspec/lib.design-system": "3.9.0",
-    "@contractspec/lib.surface-runtime": "0.5.19",
+    "@contractspec/lib.contracts-spec": "5.4.0",
+    "@contractspec/lib.contracts-library": "3.7.20",
+    "@contractspec/lib.content-gen": "3.7.20",
+    "@contractspec/lib.contracts-runtime-server-mcp": "3.7.20",
+    "@contractspec/lib.design-system": "3.10.0",
+    "@contractspec/lib.surface-runtime": "0.5.20",
     "@contractspec/lib.provider-ranking": "0.7.13",
-    "@contractspec/lib.example-shared-ui": "6.0.19",
-    "@contractspec/lib.knowledge": "3.7.19",
+    "@contractspec/lib.example-shared-ui": "6.0.20",
+    "@contractspec/lib.knowledge": "3.7.20",
     "@contractspec/lib.logger": "3.7.13",
     "@contractspec/lib.runtime-sandbox": "2.7.14",
     "@contractspec/lib.schema": "3.7.14",
-    "@contractspec/lib.ui-kit-web": "3.10.0",
+    "@contractspec/lib.ui-kit-web": "3.10.1",
     "@contractspec/lib.ui-link": "3.7.15",
-    "@contractspec/module.context-storage": "0.7.18",
-    "@contractspec/module.examples": "3.8.11",
+    "@contractspec/module.context-storage": "0.7.19",
+    "@contractspec/module.examples": "3.9.0",
     "@dnd-kit/core": "^6.1.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -1936,10 +1961,10 @@
     "posthog-react-native": "^4.41.1",
     "react-hook-form": "^7.72.1",
     "zod": "^4.3.5",
-    "@contractspec/lib.contracts-integrations": "3.8.11",
-    "@contractspec/lib.contracts-runtime-server-rest": "3.7.19",
-    "@contractspec/lib.contracts-runtime-server-graphql": "3.7.19",
-    "@contractspec/lib.contracts-runtime-client-react": "3.9.0"
+    "@contractspec/lib.contracts-integrations": "3.8.12",
+    "@contractspec/lib.contracts-runtime-server-rest": "3.7.20",
+    "@contractspec/lib.contracts-runtime-server-graphql": "3.7.20",
+    "@contractspec/lib.contracts-runtime-client-react": "3.9.1"
   },
   "devDependencies": {
     "@types/react": "~19.2.14",
@@ -1987,6 +2012,12 @@
         "node": "./dist/node/application/mcp/cliMcp.js",
         "default": "./dist/application/mcp/cliMcp.js"
       },
+      "./application/mcp/cliMcp.onboarding": {
+        "types": "./dist/application/mcp/cliMcp.onboarding.d.ts",
+        "bun": "./dist/application/mcp/cliMcp.onboarding.js",
+        "node": "./dist/node/application/mcp/cliMcp.onboarding.js",
+        "default": "./dist/application/mcp/cliMcp.onboarding.js"
+      },
       "./application/mcp/common": {
         "types": "./dist/application/mcp/common.d.ts",
         "bun": "./dist/application/mcp/common.js",
@@ -1999,6 +2030,12 @@
         "node": "./dist/node/application/mcp/contractsMcp.js",
         "default": "./dist/application/mcp/contractsMcp.js"
       },
+      "./application/mcp/contractsMcpAdoptionTools": {
+        "types": "./dist/application/mcp/contractsMcpAdoptionTools.d.ts",
+        "bun": "./dist/application/mcp/contractsMcpAdoptionTools.js",
+        "node": "./dist/node/application/mcp/contractsMcpAdoptionTools.js",
+        "default": "./dist/application/mcp/contractsMcpAdoptionTools.js"
+      },
       "./application/mcp/contractsMcpResources": {
         "types": "./dist/application/mcp/contractsMcpResources.d.ts",
         "bun": "./dist/application/mcp/contractsMcpResources.js",
@@ -2437,6 +2474,12 @@
         "node": "./dist/node/components/docs/guides/GuideNextjsOneEndpointPage.js",
         "default": "./dist/components/docs/guides/GuideNextjsOneEndpointPage.js"
       },
+      "./components/docs/guides/GuideReleaseCapsulesPage": {
+        "types": "./dist/components/docs/guides/GuideReleaseCapsulesPage.d.ts",
+        "bun": "./dist/components/docs/guides/GuideReleaseCapsulesPage.js",
+        "node": "./dist/node/components/docs/guides/GuideReleaseCapsulesPage.js",
+        "default": "./dist/components/docs/guides/GuideReleaseCapsulesPage.js"
+      },
       "./components/docs/guides/guides.docblocks": {
         "types": "./dist/components/docs/guides/guides.docblocks.d.ts",
         "bun": "./dist/components/docs/guides/guides.docblocks.js",
@@ -2821,6 +2864,12 @@
         "node": "./dist/node/components/docs/libraries/LibrariesUIKitPage.js",
         "default": "./dist/components/docs/libraries/LibrariesUIKitPage.js"
       },
+      "./components/docs/libraries/LibrariesUIKitWebPage": {
+        "types": "./dist/components/docs/libraries/LibrariesUIKitWebPage.d.ts",
+        "bun": "./dist/components/docs/libraries/LibrariesUIKitWebPage.js",
+        "node": "./dist/node/components/docs/libraries/LibrariesUIKitWebPage.js",
+        "default": "./dist/components/docs/libraries/LibrariesUIKitWebPage.js"
+      },
       "./components/docs/libraries/LibrariesWorkflowComposerPage": {
         "types": "./dist/components/docs/libraries/LibrariesWorkflowComposerPage.d.ts",
         "bun": "./dist/components/docs/libraries/LibrariesWorkflowComposerPage.js",

package/src/application/mcp/cliMcp.onboarding.ts

@@ -0,0 +1,297 @@
+import { createNodeAdapters, onboarding } from '@contractspec/bundle.workspace';
+import {
+	defineCommand,
+	definePrompt,
+	defineResourceTemplate,
+	installOp,
+	type OperationSpecRegistry,
+	type PromptRegistry,
+	type ResourceRegistry,
+} from '@contractspec/lib.contracts-spec';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import z from 'zod';
+
+const ONBOARDING_TAGS = ['cli', 'mcp', 'onboarding'];
+const ONBOARDING_OWNERS = ['@contractspec'];
+
+function parseTrackIds(tracks: string | undefined) {
+	return tracks
+		?.split(',')
+		.map((track) => track.trim())
+		.filter(Boolean) as onboarding.OnboardingTrackId[] | undefined;
+}
+
+async function buildPlan(args: { tracks?: string; example?: string } = {}) {
+	const adapters = createNodeAdapters({
+		cwd: process.cwd(),
+		silent: true,
+	});
+	return onboarding.buildOnboardingPlan(adapters, {
+		forcedExampleKey: args.example,
+		selectedTracks: parseTrackIds(args.tracks),
+	});
+}
+
+export function registerCliOnboardingResources(resources: ResourceRegistry) {
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'onboarding://tracks',
+				title: 'Onboarding tracks',
+				description:
+					'Primary ContractSpec onboarding tracks exposed by the CLI.',
+				mimeType: 'application/json',
+				tags: ONBOARDING_TAGS,
+			},
+			input: z.object({}),
+			resolve: async () => ({
+				uri: 'onboarding://tracks',
+				mimeType: 'application/json',
+				data: JSON.stringify(onboarding.listOnboardingTracks(), null, 2),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'onboarding://track/{id}',
+				title: 'Onboarding track',
+				description:
+					'Track-specific onboarding metadata and recommended commands.',
+				mimeType: 'application/json',
+				tags: ONBOARDING_TAGS,
+			},
+			input: z.object({ id: z.string() }),
+			resolve: async ({ id }) => ({
+				uri: `onboarding://track/${id}`,
+				mimeType: 'application/json',
+				data: JSON.stringify(
+					onboarding.getOnboardingTrack(id) ?? null,
+					null,
+					2
+				),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'onboarding://artifacts/{id}{?tracks,example}',
+				title: 'Rendered onboarding artifact',
+				description:
+					'Render AGENTS.md or USAGE.md content for the current repo.',
+				mimeType: 'text/markdown',
+				tags: ONBOARDING_TAGS,
+			},
+			input: z.object({
+				example: z.string().optional(),
+				id: z.enum(['agent-guide', 'human-guide']),
+				tracks: z.string().optional(),
+			}),
+			resolve: async ({ example, id, tracks }) => {
+				const plan = await buildPlan({ example, tracks });
+				return {
+					uri: `onboarding://artifacts/${id}`,
+					mimeType: 'text/markdown',
+					data:
+						id === 'agent-guide'
+							? plan.guides.agentGuide
+							: plan.guides.humanGuide,
+				};
+			},
+		})
+	);
+}
+
+export function registerCliOnboardingPrompts(prompts: PromptRegistry) {
+	prompts.register(
+		definePrompt({
+			meta: {
+				key: 'cli.onboarding',
+				version: '1.0.0',
+				title: 'Plan a ContractSpec onboarding flow',
+				description:
+					'Suggest the right onboarding track and artifacts for a repo.',
+				tags: ONBOARDING_TAGS,
+				stability: 'beta',
+				owners: ONBOARDING_OWNERS,
+			},
+			args: [
+				{
+					name: 'goal',
+					description: 'Repository onboarding goal or focus area.',
+					required: false,
+					schema: z.string().optional(),
+				},
+			],
+			input: z.object({ goal: z.string().optional() }),
+			render: async ({ goal }) => [
+				{
+					type: 'text',
+					text: `Use onboarding://tracks and onboarding_suggestTracks-v1_0_0 before recommending repo-local ContractSpec adoption steps.${goal ? ` Goal: ${goal}.` : ''}`,
+				},
+				{
+					type: 'resource' as const,
+					uri: 'onboarding://tracks',
+					title: 'Tracks',
+				},
+			],
+		})
+	);
+}
+
+export function registerCliOnboardingOps(registry: OperationSpecRegistry) {
+	const SuggestTracksInput = defineSchemaModel({
+		name: 'OnboardingSuggestTracksInput',
+		fields: {
+			example: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+			tracks: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		},
+	});
+	const SuggestTracksOutput = defineSchemaModel({
+		name: 'OnboardingSuggestTracksOutput',
+		fields: {
+			nextCommands: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isArray: true,
+				isOptional: false,
+			},
+			primaryTrack: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+			reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			tracks: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isArray: true,
+				isOptional: false,
+			},
+		},
+	});
+	const RenderArtifactsOutput = defineSchemaModel({
+		name: 'OnboardingRenderArtifactOutput',
+		fields: {
+			content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+			primaryTrack: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+		},
+	});
+	const NextCommandOutput = defineSchemaModel({
+		name: 'OnboardingNextCommandOutput',
+		fields: {
+			nextCommand: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+			primaryTrack: {
+				type: ScalarTypeEnum.String_unsecure(),
+				isOptional: false,
+			},
+		},
+	});
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'onboarding.suggestTracks',
+				version: '1.0.0',
+				stability: 'stable',
+				owners: ONBOARDING_OWNERS,
+				tags: ONBOARDING_TAGS,
+				description: 'Suggest the recommended ContractSpec onboarding tracks.',
+				goal: 'Help agents choose the right onboarding track before editing repo-local guides.',
+				context: 'Used inside the CLI MCP server.',
+			},
+			io: { input: SuggestTracksInput, output: SuggestTracksOutput },
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ example, tracks }) => {
+			const plan = await buildPlan({ example, tracks });
+			return {
+				nextCommands: plan.nextCommands,
+				primaryTrack: plan.primaryTrack.id,
+				reason: plan.recommendations[0]?.reason ?? plan.primaryTrack.summary,
+				tracks: plan.recommendations.map(
+					(recommendation) => recommendation.track.id
+				),
+			};
+		}
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'onboarding.renderArtifacts',
+				version: '1.0.0',
+				stability: 'stable',
+				owners: ONBOARDING_OWNERS,
+				tags: ONBOARDING_TAGS,
+				description: 'Render onboarding artifacts for the current repo.',
+				goal: 'Provide AGENTS.md or USAGE.md content without mutating the repo.',
+				context: 'Used inside the CLI MCP server.',
+			},
+			io: {
+				input: defineSchemaModel({
+					name: 'OnboardingRenderArtifactInput',
+					fields: {
+						artifact: {
+							type: ScalarTypeEnum.String_unsecure(),
+							isOptional: false,
+						},
+						example: {
+							type: ScalarTypeEnum.String_unsecure(),
+							isOptional: true,
+						},
+						tracks: {
+							type: ScalarTypeEnum.String_unsecure(),
+							isOptional: true,
+						},
+					},
+				}),
+				output: RenderArtifactsOutput,
+			},
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ artifact, example, tracks }) => {
+			const plan = await buildPlan({ example, tracks });
+			return {
+				content:
+					artifact === 'agent-guide'
+						? plan.guides.agentGuide
+						: plan.guides.humanGuide,
+				primaryTrack: plan.primaryTrack.id,
+			};
+		}
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'onboarding.nextCommand',
+				version: '1.0.0',
+				stability: 'stable',
+				owners: ONBOARDING_OWNERS,
+				tags: ONBOARDING_TAGS,
+				description: 'Return the next recommended CLI command for onboarding.',
+				goal: 'Help agents choose the next onboarding command without mutating the repo.',
+				context: 'Used inside the CLI MCP server.',
+			},
+			io: { input: SuggestTracksInput, output: NextCommandOutput },
+			policy: { auth: 'anonymous' },
+		}),
+		async ({ example, tracks }) => {
+			const plan = await buildPlan({ example, tracks });
+			return {
+				nextCommand: plan.nextCommands[0] ?? 'contractspec onboard',
+				primaryTrack: plan.primaryTrack.id,
+			};
+		}
+	);
+}

package/src/application/mcp/cliMcp.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'bun:test';
+import { Elysia } from 'elysia';
+import { createCliMcpHandler } from './cliMcp';
+
+function createTestApp() {
+	return new Elysia().use(createCliMcpHandler('/mcp/cli'));
+}
+
+async function mcpRequest(
+	method: string,
+	params: Record<string, unknown> = {}
+) {
+	return createTestApp().handle(
+		new Request('http://localhost/mcp/cli', {
+			method: 'POST',
+			headers: {
+				accept: 'application/json',
+				'content-type': 'application/json',
+			},
+			body: JSON.stringify({
+				jsonrpc: '2.0',
+				id: 1,
+				method,
+				params,
+			}),
+		})
+	);
+}
+
+async function initialize() {
+	const response = await mcpRequest('initialize', {
+		protocolVersion: '2024-11-05',
+		capabilities: {},
+		clientInfo: { name: 'cli-mcp-test', version: '1.0.0' },
+	});
+	expect(response.status).toBe(200);
+}
+
+describe('cli MCP handler', () => {
+	it('exposes onboarding resources, prompts, and tools', async () => {
+		await initialize();
+
+		const toolsResponse = await mcpRequest('tools/list');
+		const toolsBody = await toolsResponse.json();
+		const toolNames = toolsBody.result.tools.map(
+			(tool: { name: string }) => tool.name
+		);
+		expect(toolNames).toContain('cli_suggestCommand-v1_0_0');
+		expect(toolNames).toContain('onboarding_suggestTracks-v1_0_0');
+		expect(toolNames).toContain('onboarding_renderArtifacts-v1_0_0');
+		expect(toolNames).toContain('onboarding_nextCommand-v1_0_0');
+
+		const promptsResponse = await mcpRequest('prompts/list');
+		const promptsBody = await promptsResponse.json();
+		const promptNames = promptsBody.result.prompts.map(
+			(prompt: { name: string }) => prompt.name
+		);
+		expect(promptNames).toContain('cli_usage');
+		expect(promptNames).toContain('cli_onboarding');
+
+		const resourcesResponse = await mcpRequest('resources/list');
+		const resourcesBody = await resourcesResponse.json();
+		const resourceUris = (resourcesBody.result.resources ?? []).map(
+			(resource: { uri?: string; uriTemplate?: string }) =>
+				resource.uriTemplate ?? resource.uri
+		);
+		expect(resourceUris).toContain('cli://commands');
+		expect(resourceUris).toContain('onboarding://tracks');
+	});
+
+	it('renders onboarding artifacts and next-command guidance', async () => {
+		await initialize();
+
+		const artifactResponse = await mcpRequest('tools/call', {
+			name: 'onboarding_renderArtifacts-v1_0_0',
+			arguments: {
+				artifact: 'human-guide',
+				tracks: 'knowledge',
+			},
+		});
+		const artifactBody = await artifactResponse.json();
+		const artifactResult = JSON.parse(artifactBody.result.content[0].text);
+		expect(artifactResult.primaryTrack).toBe('knowledge');
+		expect(artifactResult.content).toContain('ContractSpec Repo Onboarding');
+
+		const nextCommandResponse = await mcpRequest('tools/call', {
+			name: 'onboarding_nextCommand-v1_0_0',
+			arguments: {
+				tracks: 'ai-agents',
+			},
+		});
+		const nextCommandBody = await nextCommandResponse.json();
+		const nextCommandResult = JSON.parse(
+			nextCommandBody.result.content[0].text
+		);
+		expect(nextCommandResult.primaryTrack).toBe('ai-agents');
+		expect(nextCommandResult.nextCommand).toContain('contractspec onboard');
+	});
+});

package/src/application/mcp/cliMcp.ts

@@ -12,6 +12,11 @@ import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 import path from 'path';
 import z from 'zod';
 import { appLogger } from '../../infrastructure/elysia/logger';
+import {
+	registerCliOnboardingOps,
+	registerCliOnboardingPrompts,
+	registerCliOnboardingResources,
+} from './cliMcp.onboarding';
 import { createMcpElysiaHandler } from './common';
 
 const CLI_DOC_PATHS = {
@@ -22,11 +27,11 @@ const CLI_DOC_PATHS = {
 
 const CLI_DOC_FALLBACK = {
 	quickstart:
-		'# ContractSpec CLI quickstart\n\ncontractspec create\ncontractspec build <spec>\ncontractspec validate <spec>',
+		'# ContractSpec CLI quickstart\n\ncontractspec quickstart\ncontractspec onboard\ncontractspec validate',
 	reference:
-		'# ContractSpec CLI reference\n\nKey commands: create, build, validate. See README for full options.',
+		'# ContractSpec CLI reference\n\nKey commands: onboard, create, generate, validate. See README for full options.',
 	readme:
-		'# ContractSpec CLI\n\nStabilize AI-generated code across API, DB, UI, events. Use create/build/validate commands.',
+		'# ContractSpec CLI\n\nStabilize AI-generated code across API, DB, UI, events. Use onboard/create/generate/validate commands.',
 };
 
 const CLI_DOC_TAGS = ['cli', 'mcp'];
@@ -108,6 +113,12 @@ function buildCliResources() {
 			input: z.object({}),
 			resolve: async () => {
 				const commands = [
+					{
+						command: 'contractspec onboard',
+						summary:
+							'Generate repo-local AGENTS.md and USAGE.md guidance plus recommended tracks.',
+						doc: 'cli://doc/quickstart',
+					},
 					{
 						command: 'contractspec create',
 						summary: 'Interactive wizard to author specs (with optional AI).',
@@ -136,6 +147,7 @@ function buildCliResources() {
 		})
 	);
 
+	registerCliOnboardingResources(resources);
 	return resources;
 }
 
@@ -178,6 +190,7 @@ function buildCliPrompts() {
 		})
 	);
 
+	registerCliOnboardingPrompts(prompts);
 	return prompts;
 }
 
@@ -224,6 +237,19 @@ function buildCliOps() {
 	installOp(registry, suggestSpec, async ({ goal, prefersAi }) => {
 		const lower = goal.toLowerCase();
 
+		if (
+			lower.includes('onboard') ||
+			lower.includes('start') ||
+			lower.includes('guide') ||
+			lower.includes('install')
+		) {
+			return {
+				command: 'contractspec onboard',
+				docUri: 'cli://doc/quickstart',
+				reason: 'Starts the CLI-first onboarding flow for the current repo.',
+			};
+		}
+
 		if (lower.includes('create') || lower.includes('new')) {
 			return {
 				command: prefersAi ? 'contractspec create --ai' : 'contractspec create',
@@ -258,6 +284,7 @@ function buildCliOps() {
 		};
 	});
 
+	registerCliOnboardingOps(registry);
 	return registry;
 }