@contractspec/bundle.workspace 4.4.0 → 4.5.1

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/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/types.d.ts

@@ -3,7 +3,7 @@ import type { SetupFileResult, SetupGitignoreBehavior, SetupPromptCallbacks } fr
 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;

package/dist/services/deps.d.ts

@@ -1,8 +1,8 @@
 /**
  * Dependency analysis service.
  */
-import { type ContractGraph, type ContractNode } from '@contractspec/module.workspace';
 import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
+import { type ContractGraph, type ContractNode } from '@contractspec/module.workspace';
 import type { FsAdapter } from '../ports/fs';
 /**
  * Options for dependency analysis.

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

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

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';
@@ -32,7 +33,9 @@ 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 * as packageDeclarations from './package-declarations/index';
 export * from './package-scaffold';
 export * from './quickstart/index';
 export * from './regenerator';
@@ -47,6 +50,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,8 +6,8 @@
  * - Unresolved references (broken event/op/presentation refs)
  * - Feature coverage metrics
  */
-import { type AnalyzedSpecType, type FeatureScanResult, type RefInfo } from '@contractspec/module.workspace';
 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';
 import { type ExtractedTestTarget } from './test-link';

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-declarations/helpers.d.ts

@@ -0,0 +1,13 @@
+import type { PackageDeclarationTarget } from '@contractspec/lib.contracts-spec/workspace-config';
+import type { WorkspacePackageKind } from './types';
+export declare function inferWorkspacePackageKind(relativePackageRoot: string): WorkspacePackageKind | null;
+export declare function getCanonicalDeclarationRelativePath(kind: WorkspacePackageKind, packageDirName: string): string;
+export declare function getIndexExportPath(kind: WorkspacePackageKind, packageDirName: string): string;
+export declare function buildPackageDeclarationKey(relativePackageRoot: string): string;
+export declare function buildPackageTitle(packageDirName: string): string;
+export declare function buildDomain(packageDirName: string): string;
+export declare function buildDeclarationTags(packageDirName: string, kind: WorkspacePackageKind, defaultTags: string[]): string[];
+export declare function matchesAllowMissing(allowMissing: string[], relativePackageRoot: string, packageName: string): boolean;
+export declare function normalizePath(value: string): string;
+export declare function toPascalCase(value: string): string;
+export declare function buildExportName(target: PackageDeclarationTarget, packageDirName: string): string;

package/dist/services/package-declarations/index.d.ts

@@ -0,0 +1,5 @@
+export * from './helpers';
+export * from './inventory';
+export * from './render';
+export * from './sync';
+export * from './types';

package/dist/services/package-declarations/inventory.d.ts

@@ -0,0 +1,4 @@
+import type { FsAdapter } from '../../ports/fs';
+import { type PackageDeclarationAuditOptions, type PackageDeclarationAuditResult, type WorkspacePackageInfo } from './types';
+export declare function discoverWorkspacePackages(fs: FsAdapter, options?: PackageDeclarationAuditOptions): Promise<WorkspacePackageInfo[]>;
+export declare function auditPackageDeclarations(fs: FsAdapter, options?: PackageDeclarationAuditOptions): Promise<PackageDeclarationAuditResult[]>;

package/dist/services/package-declarations/render.d.ts

@@ -0,0 +1,41 @@
+import type { WorkspacePackageInfo } from './types';
+export interface PackageSpecRefs {
+    operations: Array<{
+        key: string;
+        version: string;
+    }>;
+    events: Array<{
+        key: string;
+        version: string;
+    }>;
+    presentations: Array<{
+        key: string;
+        version: string;
+    }>;
+    experiments: Array<{
+        key: string;
+        version: string;
+    }>;
+    workflows: Array<{
+        key: string;
+        version: string;
+    }>;
+    dataViews: Array<{
+        key: string;
+        version: string;
+    }>;
+    capabilities: Array<{
+        key: string;
+        version: string;
+    }>;
+    features: Array<{
+        key: string;
+        version: string;
+    }>;
+}
+export declare function renderPackageDeclaration(input: {
+    pkg: WorkspacePackageInfo;
+    refs: PackageSpecRefs;
+    owners: string[];
+    defaultTags: string[];
+}): string;

package/dist/services/package-declarations/sync.d.ts

@@ -0,0 +1,8 @@
+import type { FsAdapter } from '../../ports/fs';
+import { auditPackageDeclarations } from './inventory';
+import { type PackageDeclarationSyncEntry, type PackageDeclarationSyncOptions, type PackageDeclarationSyncResult } from './types';
+export declare function syncPackageDeclarations(fs: FsAdapter, options?: PackageDeclarationSyncOptions): Promise<PackageDeclarationSyncResult>;
+export declare function createPackageDeclarationIssue(entry: PackageDeclarationSyncEntry | Awaited<ReturnType<typeof auditPackageDeclarations>>[number], allowMissing: string[]): {
+    allowlisted: boolean;
+    message: string;
+};

package/dist/services/package-declarations/sync.test.d.ts

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

package/dist/services/package-declarations/types.d.ts

@@ -0,0 +1,48 @@
+import type { PackageDeclarationConfig, PackageDeclarationRequiredByKind, PackageDeclarationTarget, ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec/workspace-config';
+export type WorkspacePackageKind = 'libs' | 'modules' | 'integrations' | 'bundles' | 'apps' | 'appsRegistry' | 'examples';
+export interface WorkspacePackageDeclarationRequirement {
+    kind: WorkspacePackageKind;
+    target: PackageDeclarationTarget;
+}
+export interface WorkspacePackageInfo {
+    workspaceRoot: string;
+    relativePackageRoot: string;
+    packageRoot: string;
+    packageName: string;
+    packageDirName: string;
+    description?: string;
+    kind: WorkspacePackageKind;
+    target: PackageDeclarationTarget;
+    canonicalDeclarationRelativePath: string;
+    canonicalDeclarationPath: string;
+    indexPath: string;
+    indexExportPath: string;
+}
+export interface PackageDeclarationAuditResult extends WorkspacePackageInfo {
+    exists: boolean;
+    matchesExpectedTarget: boolean;
+    detectedSpecType?: string;
+}
+export interface PackageDeclarationSyncEntry extends PackageDeclarationAuditResult {
+    action: 'created' | 'updated' | 'skipped';
+    declarationCreated: boolean;
+    indexUpdated: boolean;
+    packageJsonUpdated: boolean;
+    dependenciesUpdated: string[];
+}
+export interface PackageDeclarationAuditOptions {
+    config?: ResolvedContractsrcConfig;
+    workspaceRoot?: string;
+}
+export interface PackageDeclarationSyncOptions extends PackageDeclarationAuditOptions {
+    dryRun?: boolean;
+    force?: boolean;
+}
+export interface PackageDeclarationSyncResult {
+    packages: PackageDeclarationSyncEntry[];
+    createdFiles: string[];
+    updatedFiles: string[];
+}
+export declare const DEFAULT_PACKAGE_DECLARATION_REQUIRED_BY_KIND: Required<PackageDeclarationRequiredByKind>;
+export declare const WORKSPACE_PACKAGE_KIND_BY_PREFIX: Readonly<Record<string, WorkspacePackageKind>>;
+export declare function resolvePackageDeclarationConfig(config?: ResolvedContractsrcConfig): PackageDeclarationConfig;

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

@@ -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/index.d.ts

@@ -6,6 +6,9 @@
 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;

package/dist/services/setup/setup-service.d.ts

@@ -4,9 +4,24 @@
  * Orchestrates the full ContractSpec setup flow.
  * Supports both single projects and monorepos.
  */
+import { findPackageRoot, findWorkspaceRoot, getPackageName, isMonorepo } from '../../adapters/workspace';
 import type { FsAdapter } from '../../ports/fs';
-import type { SetupOptions, SetupPromptCallbacks, SetupResult } from './types';
+import { setupGitignore } from './gitignore';
+import type { SetupFileResult, SetupOptions, SetupPromptCallbacks, SetupResult, SetupTarget } from './types';
+type SetupTargetHandler = (fs: FsAdapter, options: SetupOptions, prompts: SetupPromptCallbacks) => Promise<SetupFileResult>;
+interface SetupWorkspaceAdapters {
+    findWorkspaceRoot: typeof findWorkspaceRoot;
+    findPackageRoot: typeof findPackageRoot;
+    isMonorepo: typeof isMonorepo;
+    getPackageName: typeof getPackageName;
+}
+export interface SetupServiceDeps {
+    targets?: Partial<Record<SetupTarget, SetupTargetHandler>>;
+    workspace?: Partial<SetupWorkspaceAdapters>;
+    setupGitignore?: typeof setupGitignore;
+}
 /**
  * Run the ContractSpec setup.
  */
-export declare function runSetup(fs: FsAdapter, options: SetupOptions, prompts?: SetupPromptCallbacks): Promise<SetupResult>;
+export declare function runSetup(fs: FsAdapter, options: SetupOptions, prompts?: SetupPromptCallbacks, deps?: SetupServiceDeps): Promise<SetupResult>;
+export {};

package/dist/services/setup/targets/agents-md.d.ts

@@ -3,6 +3,8 @@
  */
 import type { FsAdapter } from '../../../ports/fs';
 import type { SetupFileResult, SetupOptions, SetupPromptCallbacks } from '../types';
+export declare const CONTRACTSPEC_AGENTS_BLOCK_START = "<!-- contractspec:init:agents:start -->";
+export declare const CONTRACTSPEC_AGENTS_BLOCK_END = "<!-- contractspec:init:agents:end -->";
 /**
  * Setup AGENTS.md
  */

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

@@ -7,4 +7,5 @@ export { setupCliConfig } from './cli-config';
 export { setupCursorRules } from './cursor-rules';
 export { setupMcpClaude } from './mcp-claude';
 export { setupMcpCursor } from './mcp-cursor';
+export { setupUsageMd } from './usage-md';
 export { setupVscodeSettings } from './vscode-settings';

package/dist/services/setup/targets/usage-md.d.ts

@@ -0,0 +1,5 @@
+import type { FsAdapter } from '../../../ports/fs';
+import type { SetupFileResult, SetupOptions, SetupPromptCallbacks } from '../types';
+export declare const CONTRACTSPEC_USAGE_BLOCK_START = "<!-- contractspec:init:usage:start -->";
+export declare const CONTRACTSPEC_USAGE_BLOCK_END = "<!-- contractspec:init:usage:end -->";
+export declare function setupUsageMd(fs: FsAdapter, options: SetupOptions, prompts: SetupPromptCallbacks): Promise<SetupFileResult>;

package/dist/services/setup/targets/usage-md.test.d.ts

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

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

@@ -4,7 +4,7 @@
 /**
  * Target components that can be configured during setup.
  */
-export type SetupTarget = 'cli-config' | 'biome-config' | 'vscode-settings' | 'mcp-cursor' | 'mcp-claude' | 'cursor-rules' | 'agents-md';
+export type SetupTarget = 'cli-config' | 'biome-config' | 'vscode-settings' | 'mcp-cursor' | 'mcp-claude' | 'cursor-rules' | 'agents-md' | 'usage-md';
 /**
  * All available setup targets.
  */
@@ -46,7 +46,7 @@ export interface SetupOptions {
     projectName?: string;
     /** Default code owners. */
     defaultOwners?: string[];
-    /** Builder API base URL for managed or hybrid presets. */
+    /** Builder API base URL for Builder presets. */
     builderApiBaseUrl?: string;
     /** Builder control-plane token environment variable name. */
     builderControlPlaneTokenEnvVar?: string;

package/dist/services/test/test-generator-service.d.ts

@@ -1,18 +1,22 @@
 import type { OperationSpec } from '@contractspec/lib.contracts-spec';
 import { type TestSpec } from '@contractspec/lib.contracts-spec/tests';
 import type { LanguageModel } from 'ai';
+import { generateText } from 'ai';
 import type { LoggerAdapter } from '../../ports/logger';
 export interface TestGeneratorOptions {
     model?: LanguageModel;
     maxScenarios?: number;
 }
+type GenerateText = typeof generateText;
 export declare class TestGeneratorService {
     private readonly logger;
     private readonly defaultModel?;
-    constructor(logger: LoggerAdapter, defaultModel?: LanguageModel | undefined);
+    private readonly generateTextImpl;
+    constructor(logger: LoggerAdapter, defaultModel?: LanguageModel | undefined, generateTextImpl?: GenerateText);
     generateTests(spec: OperationSpec<any, any>, // Use any to satisfy generics for now
     options?: TestGeneratorOptions): Promise<TestSpec>;
     private parseResponse;
     private enrichSpec;
     private logUsage;
 }
+export {};

package/dist/services/validate/spec-validator.d.ts

@@ -26,7 +26,7 @@ export interface ValidateSpecResult {
 export interface DiscoveredSpecValidationResult extends ValidateSpecResult {
     spec: SpecScanResult;
 }
-export declare function validateScannedSpec(spec: SpecScanResult, options?: ValidateSpecOptions): ValidateSpecResult;
+export declare function validateScannedSpec(spec: SpecScanResult, options?: ValidateSpecOptions): Promise<ValidateSpecResult>;
 export declare function validateDiscoveredSpecs(specs: SpecScanResult[], options?: ValidateSpecOptions): Promise<DiscoveredSpecValidationResult[]>;
 /**
  * Validate a spec file.