@contractspec/bundle.workspace 4.3.0 → 4.5.0

package/dist/services/adoption/catalog-core.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const CORE_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-entry.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry, AdoptionFamily, AdoptionPackageKind } from './types';
+export declare function createCatalogEntry(id: string, packageRef: string, family: AdoptionFamily, packageKind: AdoptionPackageKind, resolutionPriority: number, capabilityTags: string[], preferredUseCases: string[], description: string, options?: Partial<Pick<AdoptionCatalogEntry, 'avoidWhen' | 'platforms' | 'replacementImportHints' | 'runtimes' | 'title'>>): AdoptionCatalogEntry;

package/dist/services/adoption/catalog-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const RUNTIME_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-shared.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const SHARED_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-solutions.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const SOLUTION_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-ui.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const UI_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { AdoptionCatalogDocument, AdoptionCatalogEntry } from './types';
+export declare function getContractSpecAdoptionCatalog(): AdoptionCatalogEntry[];
+export declare function createAdoptionCatalogDocument(now?: Date): AdoptionCatalogDocument;

package/dist/services/adoption/index.d.ts

@@ -0,0 +1,6 @@
+export * from './catalog';
+export * from './resolve';
+export * from './tokens';
+export * from './types';
+export * from './workspace';
+export * from './workspace-scan';

package/dist/services/adoption/resolve.d.ts

@@ -0,0 +1,6 @@
+import type { AdoptionResolution, AdoptionResolveInput, AdoptionResolverRuntime, AdoptionSyncInput } from './types';
+export declare function resolveAdoption(runtime: AdoptionResolverRuntime, input: AdoptionResolveInput): Promise<AdoptionResolution>;
+export declare function syncAdoptionCatalog(runtime: AdoptionResolverRuntime, input?: AdoptionSyncInput): Promise<{
+    catalog: import("./types").AdoptionCatalogDocument;
+    catalogPath: string;
+}>;

package/dist/services/adoption/resolve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/adoption/tokens.d.ts

@@ -0,0 +1,6 @@
+import type { AdoptionCandidate } from './types';
+export declare function normalizeText(value: string): string;
+export declare function tokenize(value: string): string[];
+export declare function uniqueTokens(values: string[]): string[];
+export declare function candidateTokens(candidate: AdoptionCandidate): string[];
+export declare function overlap(left: string[], right: string[]): number;

package/dist/services/adoption/types.d.ts

@@ -0,0 +1,99 @@
+import type { ConnectAdoptionConfig, ConnectAdoptionFamily, ConnectVerdict, ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec/workspace-config';
+import type { FsAdapter } from '../../ports/fs';
+export type AdoptionFamily = ConnectAdoptionFamily;
+export type AdoptionVerdict = ConnectVerdict;
+export type AdoptionSource = 'workspace' | 'contractspec' | 'ecosystem';
+export type AdoptionPackageKind = 'primitive' | 'adapter' | 'module' | 'bundle' | 'app' | 'example';
+export interface AdoptionImportHint {
+    from: string;
+    to: string;
+    note?: string;
+}
+export interface AdoptionCatalogEntry {
+    id: string;
+    source: Exclude<AdoptionSource, 'workspace'>;
+    packageRef: string;
+    family: AdoptionFamily;
+    packageKind: AdoptionPackageKind;
+    title: string;
+    description: string;
+    capabilityTags: string[];
+    preferredUseCases: string[];
+    avoidWhen?: string[];
+    platforms?: string[];
+    runtimes?: string[];
+    replacementImportHints?: AdoptionImportHint[];
+    resolutionPriority: number;
+}
+export interface AdoptionWorkspaceCandidate {
+    id: string;
+    source: 'workspace';
+    family: AdoptionFamily;
+    title: string;
+    description: string;
+    filePath?: string;
+    packageRef?: string;
+    packageKind?: AdoptionPackageKind;
+    capabilityTags: string[];
+    preferredUseCases: string[];
+    resolutionPriority: number;
+}
+export type AdoptionCandidate = AdoptionCatalogEntry | AdoptionWorkspaceCandidate;
+export interface AdoptionCatalogDocument {
+    version: 1;
+    generatedAt: string;
+    entries: AdoptionCatalogEntry[];
+}
+export interface AdoptionWorkspaceIndex {
+    packageCandidates: AdoptionWorkspaceCandidate[];
+    fileCandidates: AdoptionWorkspaceCandidate[];
+}
+export interface AdoptionResolveInput {
+    family: AdoptionFamily;
+    query?: string;
+    symbol?: string;
+    paths?: string[];
+    platform?: string;
+    runtime?: string;
+    currentTarget?: string;
+    config?: ResolvedContractsrcConfig;
+    cwd?: string;
+    workspaceRoot?: string;
+    packageRoot?: string;
+}
+export interface AdoptionResolutionCandidate {
+    candidate: AdoptionCandidate;
+    score: number;
+    matchReasons: string[];
+}
+export interface AdoptionResolution {
+    family: AdoptionFamily;
+    verdict: AdoptionVerdict;
+    selected: AdoptionResolutionCandidate | null;
+    candidates: AdoptionResolutionCandidate[];
+    ambiguous: boolean;
+    exhausted: boolean;
+    reason: string;
+    currentTarget?: string;
+    query: string;
+}
+export interface AdoptionSyncInput {
+    config?: ResolvedContractsrcConfig;
+    cwd?: string;
+    workspaceRoot?: string;
+    packageRoot?: string;
+}
+export interface AdoptionSyncResult {
+    catalogPath: string;
+    catalog: AdoptionCatalogDocument;
+}
+export interface AdoptionResolvedWorkspace {
+    cwd: string;
+    workspaceRoot: string;
+    packageRoot: string;
+    config: ResolvedContractsrcConfig;
+    adoption: NonNullable<ConnectAdoptionConfig>;
+}
+export interface AdoptionResolverRuntime {
+    fs: FsAdapter;
+}

package/dist/services/adoption/workspace-scan.d.ts

@@ -0,0 +1,8 @@
+import type { FsAdapter } from '../../ports/fs';
+import type { AdoptionFamily, AdoptionResolvedWorkspace, AdoptionWorkspaceCandidate } from './types';
+export declare function scanWorkspaceAdoptionCandidates(fs: FsAdapter, workspace: AdoptionResolvedWorkspace): Promise<{
+    fileCandidates: AdoptionWorkspaceCandidate[];
+    packageCandidates: AdoptionWorkspaceCandidate[];
+}>;
+export declare function hasLocalShadcnRegistry(fs: FsAdapter, workspace: AdoptionResolvedWorkspace): Promise<boolean>;
+export declare function inferFamilyFromPath(path: string): AdoptionFamily | null;

package/dist/services/adoption/workspace.d.ts

@@ -0,0 +1,3 @@
+import type { FsAdapter } from '../../ports/fs';
+import type { AdoptionResolvedWorkspace, AdoptionSyncInput } from './types';
+export declare function resolveAdoptionWorkspace(fs: FsAdapter, input?: AdoptionSyncInput): Promise<AdoptionResolvedWorkspace>;

package/dist/services/build.d.ts

@@ -11,7 +11,7 @@ import type { LoggerAdapter } from '../ports/logger';
 /**
  * Build target types.
  */
-export type BuildTarget = 'handler' | 'component' | 'test';
+export type BuildTarget = 'handler' | 'component' | 'test' | 'form' | 'workflow-runner' | 'data-view-renderer' | 'package-scaffold';
 /**
  * Options for building from a spec.
  */
@@ -32,6 +32,33 @@ export interface BuildSpecOptions {
      * Skip writing files (dry run).
      */
     dryRun?: boolean;
+    /**
+     * Include target-specific test artifacts in the default build plan.
+     */
+    includeTests?: boolean;
+    /**
+     * Optional runtime generation strategy supplied by higher-level callers.
+     */
+    runtimeGeneration?: RuntimeGenerationStrategy;
+}
+export type RuntimeArtifactKind = 'handler' | 'component' | 'form';
+export type RuntimeTestKind = 'handler' | 'component';
+export interface RuntimeArtifactGenerationInput {
+    kind: RuntimeArtifactKind;
+    specCode: string;
+    outputPath: string;
+    fallbackCode: string;
+}
+export interface RuntimeTestGenerationInput {
+    kind: RuntimeTestKind;
+    specCode: string;
+    outputPath: string;
+    existingCode: string;
+    fallbackCode: string;
+}
+export interface RuntimeGenerationStrategy {
+    generateArtifact?: (input: RuntimeArtifactGenerationInput) => Promise<string | null | undefined>;
+    generateTest?: (input: RuntimeTestGenerationInput) => Promise<string | null | undefined>;
 }
 /**
  * Result of a single build target.
@@ -42,6 +69,7 @@ export interface BuildTargetResult {
     success: boolean;
     skipped?: boolean;
     error?: string;
+    generatedCode?: string;
 }
 /**
  * Result of building from a spec.
@@ -49,6 +77,7 @@ export interface BuildTargetResult {
 export interface BuildSpecResult {
     specPath: string;
     specInfo: SpecScanResult;
+    targetId: string;
     results: BuildTargetResult[];
 }
 /**
@@ -59,3 +88,9 @@ export declare function buildSpec(specPath: string, adapters: {
     logger: LoggerAdapter;
     workspace?: typeof import('@contractspec/module.workspace');
 }, config: ResolvedContractsrcConfig, options?: BuildSpecOptions): Promise<BuildSpecResult>;
+/**
+ * Detect default targets based on spec type.
+ */
+export declare function resolveDefaultBuildTargets(targetId: string, options: {
+    includeTests: boolean;
+}): BuildTarget[];

package/dist/services/connect/adoption.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceAdapters } from '../../ports/logger';
+import * as adoption from '../adoption/index';
+import type { ConnectPatchVerdict, ConnectVerdict, ConnectVerifyInput } from './types';
+export declare function evaluateConnectAdoption(adapters: Pick<WorkspaceAdapters, 'fs'>, input: ConnectVerifyInput): Promise<{
+    check?: ConnectPatchVerdict['checks'][number];
+    reason?: string;
+    remediation?: string[];
+    resolution?: Awaited<ReturnType<typeof adoption.resolveAdoption>>;
+    verdict?: ConnectVerdict;
+}>;

package/dist/services/connect/init.d.ts

@@ -1,7 +1,3 @@
 import type { FsAdapter } from '../../ports/fs';
-import type { ConnectInitInput } from './types';
-export declare function initConnectWorkspace(fs: FsAdapter, input?: ConnectInitInput): Promise<{
-    configPath: string;
-    targetRoot: string;
-    action: 'created' | 'merged';
-}>;
+import type { ConnectInitInput, ConnectInitResult } from './types';
+export declare function initConnectWorkspace(fs: FsAdapter, input?: ConnectInitInput): Promise<ConnectInitResult>;

package/dist/services/connect/types.d.ts

@@ -1,8 +1,9 @@
 import type { ConnectVerdict, ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec/workspace-config';
+import type { SetupFileResult, SetupGitignoreBehavior, SetupPromptCallbacks } from '../setup/types';
 export type { ConnectVerdict };
 export type ConnectActorType = 'human' | 'agent' | 'service' | 'tool';
 export type ConnectApprovalStatus = 'not_required' | 'pending' | 'approved' | 'rejected' | 'expired';
-export type ConnectSurface = 'agent' | 'audit' | 'cli' | 'contract' | 'harness' | 'knowledge' | 'mcp' | 'runtime';
+export type ConnectSurface = 'agent' | 'audit' | 'cli' | 'contract' | 'harness' | 'integration' | 'knowledge' | 'library' | 'mcp' | 'runtime' | 'solution' | 'ui';
 export type ConnectContractKind = 'command' | 'query' | 'event' | 'policy' | 'capability';
 export interface ConnectActorRef {
     id: string;
@@ -33,6 +34,15 @@ export interface ConnectWorkspaceInput {
 }
 export interface ConnectInitInput extends ConnectWorkspaceInput {
     scope?: 'workspace' | 'package';
+    interactive?: boolean;
+    gitignoreBehavior?: SetupGitignoreBehavior;
+    prompts?: Pick<SetupPromptCallbacks, 'confirm'>;
+}
+export interface ConnectInitResult {
+    configPath: string;
+    targetRoot: string;
+    action: 'created' | 'merged';
+    gitignore: SetupFileResult;
 }
 export interface ConnectTaskInput extends ConnectWorkspaceInput {
     taskId: string;

package/dist/services/contractsrc-schema-ref.d.ts

@@ -0,0 +1,4 @@
+export declare function getBundledContractsrcSchemaRef(options: {
+    configRoot: string;
+    workspaceRoot: string;
+}): string;

package/dist/services/deps.d.ts

@@ -1,6 +1,7 @@
 /**
  * Dependency analysis service.
  */
+import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
 import { type ContractGraph, type ContractNode } from '@contractspec/module.workspace';
 import type { FsAdapter } from '../ports/fs';
 /**
@@ -11,6 +12,7 @@ export interface AnalyzeDepsOptions {
      * File pattern to search.
      */
     pattern?: string;
+    config?: ResolvedContractsrcConfig;
 }
 /**
  * Result of dependency analysis.

package/dist/services/discover.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
+import type { MaybeArray } from '@contractspec/lib.utils-typescript';
+import { type SpecScanResult } from '@contractspec/module.workspace';
+import type { FsAdapter } from '../ports/fs';
+export interface DiscoverSpecsOptions {
+    pattern?: string;
+    paths?: string[];
+    cwd?: string;
+    type?: MaybeArray<string>;
+    config?: ResolvedContractsrcConfig;
+}
+export declare function discoverSpecFiles(fs: FsAdapter, options?: DiscoverSpecsOptions): Promise<string[]>;
+export declare function discoverSpecs(adapters: {
+    fs: FsAdapter;
+}, options?: DiscoverSpecsOptions): Promise<SpecScanResult[]>;

package/dist/services/discover.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/doctor/checks/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/generate-artifacts.d.ts

@@ -1,11 +1,15 @@
+import { type ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
 import type { WorkspaceAdapters } from '../ports/logger';
 export interface GenerateArtifactsResult {
     specsCount: number;
     docsCount: number;
+    materializedCount: number;
 }
 export interface GenerateArtifactsOptions {
     scanAllSpecs?: boolean;
     specPattern?: string;
     specSearchRoot?: string;
+    config?: ResolvedContractsrcConfig;
+    includeRuntimeTests?: boolean;
 }
 export declare function generateArtifacts(adapters: WorkspaceAdapters, contractsDir: string, generatedDir: string, rootPath?: string, options?: GenerateArtifactsOptions): Promise<GenerateArtifactsResult>;

package/dist/services/index.d.ts

@@ -3,6 +3,7 @@
  */
 export * from './action-drift/index';
 export * from './action-pr';
+export * as adoption from './adoption/index';
 export * from './agent-guide/index';
 export * from './build';
 export * from './ci-check/index';
@@ -13,6 +14,7 @@ export * from './create/index';
 export * from './delete';
 export * from './deps';
 export * from './diff';
+export * from './discover';
 export * from './docs/index';
 export * from './doctor/index';
 export * from './extract';
@@ -30,7 +32,10 @@ export * from './integrity-diagram';
 export * from './layer-discovery';
 export * from './list';
 export * from './llm/index';
+export * from './module-loader';
+export * as onboarding from './onboarding/index';
 export * from './openapi/index';
+export * from './package-scaffold';
 export * from './quickstart/index';
 export * from './regenerator';
 export * from './registry';
@@ -44,6 +49,7 @@ export * from './validate/index';
 export * from './verification-cache/index';
 export * from './verify/index';
 export * as versioning from './versioning/index';
+export type { ReleaseAuthoringDraft, ReleaseAuthoringResult, ReleaseCapsuleReadIssue, SaveReleaseDraftOptions, SaveReleaseDraftResult, } from './versioning/release-service.types';
 export type { SpecVersionAnalysis } from './versioning/types';
 export * as vibe from './vibe/index';
 export * from './view/index';

package/dist/services/integrity.d.ts

@@ -6,6 +6,7 @@
  * - Unresolved references (broken event/op/presentation refs)
  * - Feature coverage metrics
  */
+import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
 import { type AnalyzedSpecType, type FeatureScanResult, type RefInfo } from '@contractspec/module.workspace';
 import type { FsAdapter } from '../ports/fs';
 import type { LoggerAdapter } from '../ports/logger';
@@ -34,6 +35,7 @@ export interface IntegrityAnalysisOptions {
      * Filter by spec type.
      */
     specType?: AnalyzedSpecType;
+    config?: ResolvedContractsrcConfig;
     /**
      * Require tests for specific spec types.
      */

package/dist/services/module-loader.d.ts

@@ -0,0 +1,25 @@
+import type { FsAdapter } from '../ports/fs';
+export interface LoadedAuthoredModule {
+    modulePath: string;
+    exports: Record<string, unknown>;
+}
+export interface LoadAuthoredModuleValueOptions<T> {
+    description: string;
+    isValue: (value: unknown) => value is T;
+    instanceKeys?: string[];
+    factoryKeys?: string[];
+}
+export declare function loadAuthoredModule(modulePath: string, options?: {
+    runtime?: 'bun' | 'node';
+}): Promise<LoadedAuthoredModule>;
+export declare function loadAuthoredModuleIfExists(modulePath: string, fs: FsAdapter): Promise<LoadedAuthoredModule | null>;
+export declare function loadAuthoredModuleExports(modulePath: string, options?: {
+    runtime?: 'bun' | 'node';
+}): Promise<Record<string, unknown>>;
+export declare function loadAuthoredModuleValue<T>(modulePath: string, options: LoadAuthoredModuleValueOptions<T>): Promise<T>;
+export declare function formatModuleLoadError(modulePath: string, error: unknown): string;
+export declare function resolveAuthoredModuleValue<T>(exports: Record<string, unknown>, modulePath: string, options: LoadAuthoredModuleValueOptions<T>): Promise<T>;
+export declare const __moduleLoaderInternals: {
+    formatModuleLoadError: typeof formatModuleLoadError;
+    resolveAuthoredModuleValue: typeof resolveAuthoredModuleValue;
+};

package/dist/services/module-loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/onboarding/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { OnboardingTrackDefinition } from './types';
+export declare const ONBOARDING_TRACKS: readonly OnboardingTrackDefinition[];
+export declare function listOnboardingTracks(): readonly OnboardingTrackDefinition[];
+export declare function getOnboardingTrack(trackId: string): OnboardingTrackDefinition | undefined;

package/dist/services/onboarding/index.d.ts

@@ -0,0 +1,4 @@
+export * from './catalog';
+export * from './render';
+export * from './service';
+export * from './types';

package/dist/services/onboarding/journey.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectSurface } from '../connect/types';
+import type { BuildOnboardingPlanInput, OnboardingBuilderMode, OnboardingPlan, OnboardingTrackDefinition, OnboardingTrackRecommendation } from './types';
+export declare function createOnboardingJourneyPlan(primaryTrack: OnboardingTrackDefinition, tracks: readonly OnboardingTrackDefinition[], workspaceRoot: string, packageRoot: string): Promise<{
+    journeyContext: import("@contractspec/lib.surface-runtime/spec").BundleContext;
+    journeyPlan: import("@contractspec/lib.surface-runtime/runtime/resolve-bundle").ResolvedSurfacePlan;
+}>;
+export declare function resolveRequestedTracks(selectedTracks: BuildOnboardingPlanInput['selectedTracks']): OnboardingTrackDefinition[];
+export declare function resolveBuilderMode(config: OnboardingPlan['config']): OnboardingBuilderMode;
+export declare function buildBuilderNextSteps(builderMode: OnboardingBuilderMode): string[];
+export declare function resolveSelectedExample(primaryTrack: OnboardingTrackDefinition, forcedExampleKey: string | undefined): import("./types").OnboardingExampleRef | undefined;
+export declare function enrichConnectSurfaces(current: readonly ConnectSurface[], recommendations: readonly OnboardingTrackRecommendation[]): ConnectSurface[];

package/dist/services/onboarding/render.d.ts

@@ -0,0 +1,5 @@
+import type { OnboardingPlan } from './types';
+export declare function renderOnboardingGuides(plan: Omit<OnboardingPlan, 'guides'>): {
+    agentGuide: string;
+    humanGuide: string;
+};

package/dist/services/onboarding/service.d.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceAdapters } from '../../ports/logger';
+import { type AdoptionResolverRuntime } from '../adoption';
+import type { BuildOnboardingPlanInput, OnboardingConnectArtifacts, OnboardingPlan } from './types';
+export declare function buildOnboardingPlan(runtime: AdoptionResolverRuntime, input?: BuildOnboardingPlanInput): Promise<OnboardingPlan>;
+export declare function createOnboardingConnectArtifacts(adapters: Pick<WorkspaceAdapters, 'fs' | 'git'>, plan: OnboardingPlan): Promise<OnboardingConnectArtifacts | undefined>;

package/dist/services/onboarding/service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/onboarding/types.d.ts

@@ -0,0 +1,71 @@
+import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec/workspace-config';
+import type { ResolvedSurfacePlan } from '@contractspec/lib.surface-runtime/runtime/resolve-bundle';
+import type { BundleContext } from '@contractspec/lib.surface-runtime/spec/types';
+import type { AdoptionFamily, AdoptionResolution } from '../adoption/types';
+import type { ConnectContextPack, ConnectPlanPacket, ConnectSurface } from '../connect/types';
+export type OnboardingTrackId = 'contracts' | 'ui-design' | 'knowledge' | 'ai-agents' | 'learning-journey';
+export type OnboardingBuilderMode = 'none' | 'managed' | 'local' | 'hybrid';
+export interface OnboardingExampleRef {
+    key: string;
+    packageRef: string;
+    title: string;
+    summary: string;
+}
+export interface OnboardingTrackDefinition {
+    id: OnboardingTrackId;
+    title: string;
+    summary: string;
+    description: string;
+    reuseFamily: AdoptionFamily;
+    adoptionQuery: string;
+    adoptionPlatform?: string;
+    primaryDocsRoute: string;
+    secondaryDocsRoutes: string[];
+    packages: string[];
+    recommendedCommands: string[];
+    starterExample: OnboardingExampleRef;
+    advancedExample?: OnboardingExampleRef;
+    connectSurfaces: ConnectSurface[];
+}
+export interface OnboardingTrackRecommendation {
+    track: OnboardingTrackDefinition;
+    selected: boolean;
+    score: number;
+    reason: string;
+    resolution: AdoptionResolution;
+}
+export interface OnboardingGuideRenderResult {
+    agentGuide: string;
+    humanGuide: string;
+}
+export interface BuildOnboardingPlanInput {
+    cwd?: string;
+    workspaceRoot?: string;
+    packageRoot?: string;
+    config?: ResolvedContractsrcConfig;
+    selectedTracks?: OnboardingTrackId[];
+    forcedExampleKey?: string;
+    agentGuidePath?: string;
+    humanGuidePath?: string;
+}
+export interface OnboardingPlan {
+    cwd: string;
+    workspaceRoot: string;
+    packageRoot: string;
+    config: ResolvedContractsrcConfig;
+    builderMode: OnboardingBuilderMode;
+    primaryTrack: OnboardingTrackDefinition;
+    recommendations: OnboardingTrackRecommendation[];
+    journeyContext: BundleContext;
+    journeyPlan: ResolvedSurfacePlan;
+    guides: OnboardingGuideRenderResult;
+    agentGuidePath: string;
+    humanGuidePath: string;
+    selectedExample: OnboardingExampleRef;
+    nextCommands: string[];
+    builderNextSteps: string[];
+}
+export interface OnboardingConnectArtifacts {
+    contextPack: ConnectContextPack;
+    planPacket: ConnectPlanPacket;
+}

package/dist/services/package-scaffold.d.ts

@@ -0,0 +1,22 @@
+import type { AuthoringTargetId } from '@contractspec/module.workspace';
+import type { FsAdapter } from '../ports/fs';
+export interface PackageScaffoldOptions {
+    target: Extract<AuthoringTargetId, 'module-bundle' | 'builder-spec' | 'provider-spec'>;
+    specPath: string;
+    specCode: string;
+    overwrite?: boolean;
+}
+export interface PackageScaffoldResult {
+    packageRoot: string;
+    files: string[];
+    created: string[];
+    skipped: string[];
+}
+export declare function ensurePackageScaffold(fs: FsAdapter, options: PackageScaffoldOptions): Promise<PackageScaffoldResult>;
+export declare function createPackageTargetSpecSource(input: {
+    target: PackageScaffoldOptions['target'];
+    key: string;
+    title: string;
+    description: string;
+    exportName: string;
+}): string;

package/dist/services/setup/config-generators.d.ts

@@ -13,7 +13,7 @@ export declare function generateContractsrcConfig(options: SetupOptions): object
 /**
  * Generate .vscode/settings.json ContractSpec settings.
  */
-export declare function generateVscodeSettings(): object;
+export declare function generateVscodeSettings(options: SetupOptions): object;
 /**
  * Generate .cursor/mcp.json content.
  */
@@ -33,6 +33,10 @@ export declare function generateCursorRules(options: SetupOptions): string;
  * Generate AGENTS.md content.
  */
 export declare function generateAgentsGuide(options: SetupOptions): string;
+/**
+ * Generate USAGE.md content.
+ */
+export declare function generateUsageGuide(options: SetupOptions): string;
 /**
  * Get the file path for Claude Desktop config based on platform.
  */

package/dist/services/setup/gitignore.d.ts

@@ -0,0 +1,10 @@
+import type { FsAdapter } from '../../ports/fs';
+import type { SetupFileResult, SetupGitignoreBehavior, SetupPromptCallbacks } from './types';
+export declare function setupGitignore(fs: FsAdapter, input: {
+    interactive: boolean;
+    patterns: string[];
+    root: string;
+    behavior?: SetupGitignoreBehavior;
+    prompts?: Pick<SetupPromptCallbacks, 'confirm'>;
+}): Promise<SetupFileResult>;
+export declare function mergeGitignoreContent(existingContent: string, patterns: string[]): string;

package/dist/services/setup/gitignore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/setup/index.d.ts

@@ -5,5 +5,10 @@
  */
 export * from './config-generators';
 export * from './file-merger';
+export * from './gitignore';
+export * from './managed-markdown';
+export * from './presets';
 export * from './setup-service';
+export * from './targets/agents-md';
+export * from './targets/usage-md';
 export * from './types';

package/dist/services/setup/managed-markdown.d.ts

@@ -0,0 +1,8 @@
+export interface ManagedMarkdownSectionConfig {
+    startMarker: string;
+    endMarker: string;
+    note: string;
+}
+export declare function mergeManagedMarkdown(existingContent: string, managedContent: string, config: ManagedMarkdownSectionConfig, legacyContent?: string): string;
+export declare function renderManagedMarkdownBlock(managedContent: string, config: ManagedMarkdownSectionConfig): string;
+export declare function normalizeMarkdownContent(content: string): string;