@contractspec/example.learning-journey-studio-onboarding 0.0.0-canary-20260113162409

package/dist/tests/operations.test-spec.js

@@ -0,0 +1,36 @@
+import { defineTestSpec } from "@contractspec/lib.contracts";
+
+//#region src/tests/operations.test-spec.ts
+const GetTrackTest = defineTestSpec({
+	meta: {
+		key: "learningJourney.studioOnboarding.getTrack.test",
+		version: "1.0.0",
+		stability: "experimental",
+		owners: ["@example.learning-journey-studio-onboarding"],
+		description: "Test for getting studio onboarding track",
+		tags: ["test"]
+	},
+	target: {
+		type: "operation",
+		operation: {
+			key: "learningJourney.studioOnboarding.getTrack",
+			version: "1.0.0"
+		}
+	},
+	scenarios: [{
+		key: "success",
+		when: { operation: { key: "learningJourney.studioOnboarding.getTrack" } },
+		then: [{
+			type: "expectOutput",
+			match: {}
+		}]
+	}, {
+		key: "error",
+		when: { operation: { key: "learningJourney.studioOnboarding.getTrack" } },
+		then: [{ type: "expectError" }]
+	}]
+});
+
+//#endregion
+export { GetTrackTest };
+//# sourceMappingURL=operations.test-spec.js.map

package/dist/tests/operations.test-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.test-spec.js","names":[],"sources":["../../src/tests/operations.test-spec.ts"],"sourcesContent":["import { defineTestSpec } from '@contractspec/lib.contracts';\n\nexport const GetTrackTest = defineTestSpec({\n  meta: {\n    key: 'learningJourney.studioOnboarding.getTrack.test',\n    version: '1.0.0',\n    stability: 'experimental',\n    owners: ['@example.learning-journey-studio-onboarding'],\n    description: 'Test for getting studio onboarding track',\n    tags: ['test'],\n  },\n  target: {\n    type: 'operation',\n    operation: {\n      key: 'learningJourney.studioOnboarding.getTrack',\n      version: '1.0.0',\n    },\n  },\n  scenarios: [\n    {\n      key: 'success',\n      when: { operation: { key: 'learningJourney.studioOnboarding.getTrack' } },\n      then: [{ type: 'expectOutput', match: {} }],\n    },\n    {\n      key: 'error',\n      when: { operation: { key: 'learningJourney.studioOnboarding.getTrack' } },\n      then: [{ type: 'expectError' }],\n    },\n  ],\n});\n"],"mappings":";;;AAEA,MAAa,eAAe,eAAe;CACzC,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,8CAA8C;EACvD,aAAa;EACb,MAAM,CAAC,OAAO;EACf;CACD,QAAQ;EACN,MAAM;EACN,WAAW;GACT,KAAK;GACL,SAAS;GACV;EACF;CACD,WAAW,CACT;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,6CAA6C,EAAE;EACzE,MAAM,CAAC;GAAE,MAAM;GAAgB,OAAO,EAAE;GAAE,CAAC;EAC5C,EACD;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,6CAA6C,EAAE;EACzE,MAAM,CAAC,EAAE,MAAM,eAAe,CAAC;EAChC,CACF;CACF,CAAC"}

package/dist/track.d.ts

@@ -0,0 +1,8 @@
+import { LearningJourneyTrackSpec } from "@contractspec/module.learning-journey/track-spec";
+
+//#region src/track.d.ts
+declare const studioGettingStartedTrack: LearningJourneyTrackSpec;
+declare const studioLearningTracks: LearningJourneyTrackSpec[];
+//#endregion
+export { studioGettingStartedTrack, studioLearningTracks };
+//# sourceMappingURL=track.d.ts.map

package/dist/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","names":[],"sources":["../src/track.ts"],"sourcesContent":[],"mappings":";;;cAEa,2BAA2B;cAiF3B,sBAAsB"}

package/dist/track.js

@@ -0,0 +1,91 @@
+//#region src/track.ts
+const studioGettingStartedTrack = {
+	id: "studio_getting_started",
+	productId: "contractspec-studio",
+	name: "Studio Getting Started",
+	description: "First 30 minutes in Studio: create a project, edit the spec, deploy/regenerate, and try key modules.",
+	targetUserSegment: "new_studio_user",
+	targetRole: "developer",
+	totalXp: 110,
+	streakRule: {
+		hoursWindow: 48,
+		bonusXp: 25
+	},
+	completionRewards: {
+		xpBonus: 25,
+		badgeKey: "studio_first_30m"
+	},
+	steps: [
+		{
+			id: "choose_template",
+			title: "Choose a template",
+			description: "Create your first Studio project (starter template).",
+			order: 1,
+			completion: {
+				eventName: "studio.template.instantiated",
+				sourceModule: "@contractspec/bundle.studio"
+			},
+			xpReward: 20,
+			metadata: { surface: "projects" }
+		},
+		{
+			id: "edit_spec",
+			title: "Edit the spec",
+			description: "Change the spec (not generated code) and save.",
+			instructions: "Open spec editor, tweak a contract or presentation, save.",
+			order: 2,
+			completion: {
+				eventName: "spec.changed",
+				sourceModule: "@contractspec/bundle.studio"
+			},
+			xpReward: 20,
+			metadata: { surface: "spec-editor" }
+		},
+		{
+			id: "regenerate_app",
+			title: "Regenerate the app",
+			description: "Regenerate artifacts from the updated spec.",
+			order: 3,
+			completion: {
+				eventName: "regeneration.completed",
+				sourceModule: "@contractspec/lib.contracts/regenerator"
+			},
+			xpReward: 20,
+			metadata: { surface: "regenerator" }
+		},
+		{
+			id: "open_canvas",
+			title: "Open the canvas",
+			description: "Visit the canvas module for your project.",
+			order: 4,
+			completion: {
+				eventName: "module.navigated",
+				sourceModule: "@contractspec/bundle.studio",
+				payloadFilter: { moduleId: "canvas" }
+			},
+			xpReward: 20,
+			metadata: { surface: "canvas" }
+		},
+		{
+			id: "try_evolution_mode",
+			title: "Try evolution mode",
+			description: "Request a change via Evolution, then regenerate.",
+			order: 5,
+			completion: {
+				eventName: "studio.evolution.applied",
+				sourceModule: "@contractspec/lib.evolution"
+			},
+			xpReward: 30,
+			metadata: { surface: "evolution" }
+		}
+	],
+	metadata: {
+		persona: "first_run",
+		surfacedIn: ["studio/home", "studio/sidebar/learning"]
+	}
+};
+const studioLearningTracks = [studioGettingStartedTrack];
+
+//#endregion
+export { studioGettingStartedTrack, studioLearningTracks };
+//# sourceMappingURL=track.js.map

package/dist/track.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.js","names":[],"sources":["../src/track.ts"],"sourcesContent":["import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';\n\nexport const studioGettingStartedTrack: LearningJourneyTrackSpec = {\n  id: 'studio_getting_started',\n  productId: 'contractspec-studio',\n  name: 'Studio Getting Started',\n  description:\n    'First 30 minutes in Studio: create a project, edit the spec, deploy/regenerate, and try key modules.',\n  targetUserSegment: 'new_studio_user',\n  targetRole: 'developer',\n  totalXp: 110,\n  streakRule: { hoursWindow: 48, bonusXp: 25 },\n  completionRewards: { xpBonus: 25, badgeKey: 'studio_first_30m' },\n  steps: [\n    {\n      id: 'choose_template',\n      title: 'Choose a template',\n      description: 'Create your first Studio project (starter template).',\n      order: 1,\n      completion: {\n        eventName: 'studio.template.instantiated',\n        sourceModule: '@contractspec/bundle.studio',\n      },\n      xpReward: 20,\n      metadata: { surface: 'projects' },\n    },\n    {\n      id: 'edit_spec',\n      title: 'Edit the spec',\n      description: 'Change the spec (not generated code) and save.',\n      instructions: 'Open spec editor, tweak a contract or presentation, save.',\n      order: 2,\n      completion: {\n        eventName: 'spec.changed',\n        sourceModule: '@contractspec/bundle.studio',\n      },\n      xpReward: 20,\n      metadata: { surface: 'spec-editor' },\n    },\n    {\n      id: 'regenerate_app',\n      title: 'Regenerate the app',\n      description: 'Regenerate artifacts from the updated spec.',\n      order: 3,\n      completion: {\n        eventName: 'regeneration.completed',\n        sourceModule: '@contractspec/lib.contracts/regenerator',\n      },\n      xpReward: 20,\n      metadata: { surface: 'regenerator' },\n    },\n    {\n      id: 'open_canvas',\n      title: 'Open the canvas',\n      description: 'Visit the canvas module for your project.',\n      order: 4,\n      completion: {\n        eventName: 'module.navigated',\n        sourceModule: '@contractspec/bundle.studio',\n        payloadFilter: { moduleId: 'canvas' },\n      },\n      xpReward: 20,\n      metadata: { surface: 'canvas' },\n    },\n    {\n      id: 'try_evolution_mode',\n      title: 'Try evolution mode',\n      description: 'Request a change via Evolution, then regenerate.',\n      order: 5,\n      completion: {\n        eventName: 'studio.evolution.applied',\n        sourceModule: '@contractspec/lib.evolution',\n      },\n      xpReward: 30,\n      metadata: { surface: 'evolution' },\n    },\n  ],\n  metadata: {\n    persona: 'first_run',\n    surfacedIn: ['studio/home', 'studio/sidebar/learning'],\n  },\n};\n\nexport const studioLearningTracks: LearningJourneyTrackSpec[] = [\n  studioGettingStartedTrack,\n];\n"],"mappings":";AAEA,MAAa,4BAAsD;CACjE,IAAI;CACJ,WAAW;CACX,MAAM;CACN,aACE;CACF,mBAAmB;CACnB,YAAY;CACZ,SAAS;CACT,YAAY;EAAE,aAAa;EAAI,SAAS;EAAI;CAC5C,mBAAmB;EAAE,SAAS;EAAI,UAAU;EAAoB;CAChE,OAAO;EACL;GACE,IAAI;GACJ,OAAO;GACP,aAAa;GACb,OAAO;GACP,YAAY;IACV,WAAW;IACX,cAAc;IACf;GACD,UAAU;GACV,UAAU,EAAE,SAAS,YAAY;GAClC;EACD;GACE,IAAI;GACJ,OAAO;GACP,aAAa;GACb,cAAc;GACd,OAAO;GACP,YAAY;IACV,WAAW;IACX,cAAc;IACf;GACD,UAAU;GACV,UAAU,EAAE,SAAS,eAAe;GACrC;EACD;GACE,IAAI;GACJ,OAAO;GACP,aAAa;GACb,OAAO;GACP,YAAY;IACV,WAAW;IACX,cAAc;IACf;GACD,UAAU;GACV,UAAU,EAAE,SAAS,eAAe;GACrC;EACD;GACE,IAAI;GACJ,OAAO;GACP,aAAa;GACb,OAAO;GACP,YAAY;IACV,WAAW;IACX,cAAc;IACd,eAAe,EAAE,UAAU,UAAU;IACtC;GACD,UAAU;GACV,UAAU,EAAE,SAAS,UAAU;GAChC;EACD;GACE,IAAI;GACJ,OAAO;GACP,aAAa;GACb,OAAO;GACP,YAAY;IACV,WAAW;IACX,cAAc;IACf;GACD,UAAU;GACV,UAAU,EAAE,SAAS,aAAa;GACnC;EACF;CACD,UAAU;EACR,SAAS;EACT,YAAY,CAAC,eAAe,0BAA0B;EACvD;CACF;AAED,MAAa,uBAAmD,CAC9D,0BACD"}

package/example.ts

@@ -0,0 +1 @@
+export { default } from './src/example';

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@contractspec/example.learning-journey-studio-onboarding",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Learning journey track for first 30 minutes in ContractSpec Studio.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/studio-onboarding.docblock": "./dist/docs/studio-onboarding.docblock.js",
+    "./example": "./dist/example.js",
+    "./handlers/demo.handlers": "./dist/handlers/demo.handlers.js",
+    "./learning-journey-studio-onboarding.feature": "./dist/learning-journey-studio-onboarding.feature.js",
+    "./operations": "./dist/operations/index.js",
+    "./presentations": "./dist/presentations/index.js",
+    "./tests/operations.test-spec": "./dist/tests/operations.test-spec.js",
+    "./track": "./dist/track.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "dependencies": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.schema": "0.0.0-canary-20260113162409",
+    "@contractspec/module.learning-journey": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./contracts": "./dist/contracts/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/studio-onboarding.docblock": "./dist/docs/studio-onboarding.docblock.js",
+      "./example": "./dist/example.js",
+      "./handlers/demo.handlers": "./dist/handlers/demo.handlers.js",
+      "./learning-journey-studio-onboarding.feature": "./dist/learning-journey-studio-onboarding.feature.js",
+      "./presentations": "./dist/presentations/index.js",
+      "./track": "./dist/track.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/learning-journey-studio-onboarding"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './studio-onboarding.docblock';

package/src/docs/studio-onboarding.docblock.ts

@@ -0,0 +1,38 @@
+import type { DocBlock } from '@contractspec/lib.contracts';
+import { registerDocBlocks } from '@contractspec/lib.contracts';
+
+const studioOnboardingDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.learning-journey.studio-onboarding',
+    title: 'Learning Journey — Studio Getting Started',
+    summary:
+      'Track that guides a new Studio user through template spawn, spec edit, regeneration, playground, and evolution.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/learning-journey/studio-onboarding',
+    tags: ['learning', 'onboarding', 'studio'],
+    body: `## Track
+- **Key**: \`studio_getting_started\`
+- **Persona**: new Studio developer, first 30 minutes
+- **Goal**: instantiate template → edit spec → regenerate → play → run evolution
+
+## Steps & Events
+1) \`choose_template\` → event \`studio.template.instantiated\`
+2) \`edit_spec\` → event \`spec.changed\` (scope: sandbox)
+3) \`regenerate_app\` → event \`regeneration.completed\`
+4) \`play_in_playground\` → event \`playground.session.started\`
+5) \`try_evolution_mode\` → event \`studio.evolution.applied\`
+
+XP: 20/20/20/20/30 with bonus 25 XP if completed within 48h (streak rule). Badge: \`studio_first_30m\`.
+
+## Wiring
+- Tracks export from \`@contractspec/example.learning-journey-studio-onboarding/track\`.
+- Use onboarding API:
+  - \`learning.onboarding.listTracks\` to surface catalog
+  - \`learning.onboarding.getProgress\` to render progress
+  - \`learning.onboarding.recordEvent\` to advance from bus events
+- Events should be emitted by Studio surfaces (template creation, spec save, regeneration, playground session start, evolution apply).`,
+  },
+];
+
+registerDocBlocks(studioOnboardingDocBlocks);

package/src/example.ts

@@ -0,0 +1,31 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'learning-journey-studio-onboarding',
+    version: '1.0.0',
+    title: 'Learning Journey — Studio Getting Started',
+    description:
+      'Onboarding track guiding a new Studio user through template spawn, spec edit, regeneration, playground, and evolution.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['learning', 'onboarding', 'studio'],
+  },
+  docs: {
+    rootDocId: 'docs.learning-journey.studio-onboarding',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-studio-onboarding',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'markdown'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/handlers/demo.handlers.ts

@@ -0,0 +1,48 @@
+import { studioGettingStartedTrack } from '../track';
+
+interface EmitParams {
+  learnerId: string;
+  occurredAt?: Date;
+}
+
+interface LearningJourneyEvent {
+  learnerId: string;
+  name: string;
+  occurredAt: Date;
+  trackId: string;
+  payload?: Record<string, unknown>;
+}
+
+type RecordEvent = (event: LearningJourneyEvent) => unknown;
+
+export const studioOnboardingEvents = [
+  'studio.template.instantiated',
+  'spec.changed',
+  'regeneration.completed',
+  'playground.session.started',
+  'studio.evolution.applied',
+] as const;
+
+export type StudioEvent = (typeof studioOnboardingEvents)[number];
+
+export const emitStudioOnboardingEvent = (
+  eventName: StudioEvent,
+  { learnerId, occurredAt = new Date() }: EmitParams,
+  record?: RecordEvent
+) => {
+  const event: LearningJourneyEvent = {
+    learnerId,
+    name: eventName,
+    occurredAt,
+    trackId: studioGettingStartedTrack.id,
+  };
+  return record ? record(event) : event;
+};
+
+export const emitAllStudioOnboardingEvents = (
+  params: EmitParams,
+  record?: RecordEvent
+) =>
+  studioOnboardingEvents.map((name) =>
+    emitStudioOnboardingEvent(name, params, record)
+  );

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './track';
+export * from './docs';
+export * from './operations';
+export * from './handlers/demo.handlers';
+export * from './presentations';
+export * from './learning-journey-studio-onboarding.feature';
+export { default as example } from './example';

package/src/learning-journey-studio-onboarding.feature.ts

@@ -0,0 +1,69 @@
+/**
+ * Learning Journey Studio Onboarding Feature Module Specification
+ *
+ * Defines the feature module for Studio onboarding journey.
+ */
+import { defineFeature } from '@contractspec/lib.contracts';
+
+/**
+ * Learning Journey Studio Onboarding feature module that bundles
+ * Studio-specific onboarding track operations and presentations.
+ */
+export const LearningJourneyStudioOnboardingFeature = defineFeature({
+  meta: {
+    key: 'learning-journey-studio-onboarding',
+    title: 'Learning Journey: Studio Onboarding',
+    description:
+      'Studio onboarding journey for getting started with ContractSpec Studio',
+    domain: 'learning-journey',
+    owners: ['@examples.learning-journey.studio-onboarding'],
+    tags: ['learning', 'onboarding', 'studio', 'journey'],
+    stability: 'experimental',
+    version: '1.0.0',
+  },
+
+  // All contract operations included in this feature
+  operations: [
+    { key: 'learningJourney.studioOnboarding.recordEvent', version: '1.0.0' },
+    { key: 'learningJourney.studioOnboarding.getTrack', version: '1.0.0' },
+  ],
+
+  // Events emitted by this feature
+  events: [],
+
+  // Presentations associated with this feature
+  presentations: [
+    { key: 'learning.journey.studio.track', version: '1.0.0' },
+    { key: 'learning.journey.studio.widget', version: '1.0.0' },
+  ],
+
+  // Link operations to their primary presentations
+  opToPresentation: [
+    {
+      op: {
+        key: 'learningJourney.studioOnboarding.getTrack',
+        version: '1.0.0',
+      },
+      pres: { key: 'learning.journey.studio.track', version: '1.0.0' },
+    },
+  ],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    {
+      key: 'learning.journey.studio.track',
+      version: '1.0.0',
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'learning.journey.studio.widget',
+      version: '1.0.0',
+      targets: ['react'],
+    },
+  ],
+
+  // Capability requirements
+  capabilities: {
+    requires: [{ key: 'identity', version: '1.0.0' }],
+  },
+});

package/src/operations/index.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  GetStudioOnboardingTrack,
+  RecordStudioOnboardingEvent,
+  studioOnboardingContracts,
+} from './index';
+import { studioGettingStartedTrack } from '../track';
+import {
+  emitStudioOnboardingEvent,
+  studioOnboardingEvents,
+} from '../handlers/demo.handlers';
+import type { StudioEvent } from '../handlers/demo.handlers';
+
+describe('studio onboarding contracts', () => {
+  it('exposes track metadata', () => {
+    expect(studioOnboardingContracts.track.id).toBe('studio_getting_started');
+    expect(studioOnboardingContracts.track.steps.length).toBeGreaterThan(0);
+    expect(GetStudioOnboardingTrack.meta.key).toBe(
+      'learningJourney.studioOnboarding.getTrack'
+    );
+  });
+
+  it('allows recording events via demo handler', async () => {
+    const step = studioGettingStartedTrack.steps[0];
+    expect(step).toBeDefined();
+    if (!step) throw new Error('Expected at least one onboarding step');
+
+    const eventName = step.completion.eventName;
+    const isStudioEvent = (value: string): value is StudioEvent =>
+      studioOnboardingEvents.includes(value as StudioEvent);
+
+    expect(isStudioEvent(eventName)).toBe(true);
+    if (!isStudioEvent(eventName)) {
+      throw new Error(`Unexpected event name: ${eventName}`);
+    }
+
+    const result = await emitStudioOnboardingEvent(eventName, {
+      learnerId: 'demo-learner',
+    });
+    expect(result).toBeDefined();
+  });
+
+  it('exposes record event contract', () => {
+    expect(RecordStudioOnboardingEvent.meta.key).toBe(
+      'learningJourney.studioOnboarding.recordEvent'
+    );
+  });
+});

package/src/operations/index.ts

@@ -0,0 +1,122 @@
+import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';
+import { defineCommand, defineQuery } from '@contractspec/lib.contracts';
+
+import { studioGettingStartedTrack } from '../track';
+
+const OWNERS = ['examples.learning-journey.studio-onboarding'] as const;
+
+const StepModel = defineSchemaModel({
+  name: 'StudioOnboardingStep',
+  description: 'Step metadata for Studio onboarding journey',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    completionEvent: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    sourceModule: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    xpReward: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    order: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+  },
+});
+
+export const StudioOnboardingTrackModel = defineSchemaModel({
+  name: 'StudioOnboardingTrack',
+  description: 'Studio onboarding track definition',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    totalXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    completionXpBonus: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+    },
+    completionBadgeKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+    },
+    streakHoursWindow: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+    },
+    streakBonusXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    steps: { type: StepModel, isArray: true, isOptional: false },
+  },
+});
+
+const TrackResponseModel = defineSchemaModel({
+  name: 'StudioOnboardingTrackResponse',
+  description: 'Response wrapper for studio onboarding track',
+  fields: {
+    track: { type: StudioOnboardingTrackModel, isOptional: false },
+  },
+});
+
+const RecordDemoEventInput = defineSchemaModel({
+  name: 'StudioOnboardingRecordEventInput',
+  description: 'Emit a demo event to advance Studio onboarding steps',
+  fields: {
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    eventName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    occurredAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+  },
+});
+
+const SuccessModel = defineSchemaModel({
+  name: 'StudioOnboardingSuccess',
+  description: 'Generic success response',
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+export const GetStudioOnboardingTrack = defineQuery({
+  meta: {
+    key: 'learningJourney.studioOnboarding.getTrack',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: [...OWNERS],
+    tags: ['learning', 'onboarding', 'studio'],
+    description: 'Fetch the Studio onboarding track definition.',
+    goal: 'Expose track metadata to UIs and templates.',
+    context: 'Called by Studio/Playground to render journey steps.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'StudioOnboardingTrackInput',
+      description: 'Track input',
+      fields: {},
+    }),
+    output: TrackResponseModel,
+  },
+  policy: { auth: 'user' },
+});
+
+export const RecordStudioOnboardingEvent = defineCommand({
+  meta: {
+    key: 'learningJourney.studioOnboarding.recordEvent',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: [...OWNERS],
+    tags: ['learning', 'onboarding', 'studio'],
+    description: 'Record an event to advance Studio onboarding progress.',
+    goal: 'Advance steps via domain events in demo/sandbox contexts.',
+    context:
+      'Called by handlers or demo scripts to emit step completion events.',
+  },
+  io: {
+    input: RecordDemoEventInput,
+    output: SuccessModel,
+  },
+  policy: { auth: 'user' },
+});
+
+export const studioOnboardingContracts = {
+  GetStudioOnboardingTrack,
+  RecordStudioOnboardingEvent,
+  track: studioGettingStartedTrack,
+};

package/src/presentations/index.ts

@@ -0,0 +1,57 @@
+import {
+  definePresentation,
+  StabilityEnum,
+  type PresentationSpecMeta,
+} from '@contractspec/lib.contracts';
+import { StudioOnboardingTrackModel } from '../operations';
+
+const baseMeta: Pick<
+  PresentationSpecMeta,
+  'domain' | 'owners' | 'tags' | 'title' | 'stability'
+> = {
+  domain: 'learning-journey',
+  title: 'Studio Onboarding',
+  owners: ['@examples.learning-journey.studio-onboarding'] as string[],
+  tags: ['learning', 'onboarding', 'studio'] as string[],
+  stability: StabilityEnum.Experimental,
+};
+
+export const StudioOnboardingTrackPresentation = definePresentation({
+  meta: {
+    key: 'learning.journey.studio.track',
+    version: '1.0.0',
+    description: 'Studio onboarding track detail',
+    goal: 'Visualize the onboarding track for the user.',
+    context: 'Displayed in the Studio dashboard.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackDetail',
+    props: StudioOnboardingTrackModel,
+  },
+  targets: ['react', 'markdown', 'application/json'],
+});
+
+export const StudioOnboardingWidgetPresentation = definePresentation({
+  meta: {
+    key: 'learning.journey.studio.widget',
+    version: '1.0.0',
+    description: 'Compact widget for Studio onboarding progress',
+    goal: 'Show quick progress summary.',
+    context: 'Displayed in the Studio sidebar or header.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackProgressWidget',
+  },
+  targets: ['react'],
+});
+
+export const studioOnboardingPresentations = [
+  StudioOnboardingTrackPresentation,
+  StudioOnboardingWidgetPresentation,
+];