@contractspec/example.learning-journey-ambient-coach 0.0.0-canary-20260113162409

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@contractspec/example.learning-journey-ambient-coach",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Ambient coach learning journey example with contextual tips and follow-up actions.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/ambient-coach.docblock": "./dist/docs/ambient-coach.docblock.js",
+    "./example": "./dist/example.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",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/module.learning-journey": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.contracts": "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",
+      "./example": "./dist/example.js",
+      "./track": "./dist/track.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/ambient-coach.docblock": "./dist/docs/ambient-coach.docblock.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-ambient-coach"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/ambient-coach.docblock.ts

@@ -0,0 +1,32 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const ambientCoachDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.learning-journey.ambient-coach',
+    title: 'Learning Journey — Ambient Coach',
+    summary:
+      'Context-aware coaching pattern that triggers tips, shows them, and marks completion when users act or acknowledge.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/learning-journey/ambient-coach',
+    tags: ['learning', 'coach', 'tips'],
+    body: `## Tracks
+- \`money_ambient_coach\`: cash buffer too high, no savings goal, irregular savings
+- \`coliving_ambient_coach\`: noise late evening, guest frequency high, shared space conflicts
+
+## Steps & Events
+- Trigger tip: \`coach.tip.triggered\` (payload includes \`tipId\`)
+- Show tip (optional UI emission): \`coach.tip.shown\`
+- Complete when acknowledged or follow-up action taken:
+  - \`coach.tip.acknowledged\`
+  - \`coach.tip.follow_up_action_taken\`
+
+## Usage
+- Tracks export from \`@contractspec/example.learning-journey-ambient-coach/track\`.
+- Registry progression is event-driven; payload filters can scope tips per category.
+- XP/engagement can be awarded on completion of each tip step.`,
+  },
+];
+
+registerDocBlocks(ambientCoachDocBlocks);

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './ambient-coach.docblock';

package/src/example.ts

@@ -0,0 +1,31 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'learning-journey-ambient-coach',
+    version: '1.0.0',
+    title: 'Learning Journey — Ambient Coach',
+    description:
+      'Ambient coaching pattern: lightweight nudges driven by context and recent progress.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['learning', 'coaching', 'ambient'],
+  },
+  docs: {
+    rootDocId: 'docs.learning-journey.ambient-coach',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-ambient-coach',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'markdown'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './track';
+export { default as example } from './example';
+import './docs';

package/src/track.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'bun:test';
+
+import { moneyAmbientCoachTrack } from './track';
+
+interface TestEvent {
+  name: string;
+  payload?: Record<string, unknown>;
+}
+
+const matchesFilter = (
+  filter: Record<string, unknown> | undefined,
+  payload: Record<string, unknown> | undefined
+) => {
+  if (!filter) return true;
+  if (!payload) return false;
+  return Object.entries(filter).every(([key, value]) => payload[key] === value);
+};
+
+describe('ambient coach track', () => {
+  it('completes steps when tips are acted upon', () => {
+    const tipIds = [
+      'cash_buffer_too_high',
+      'no_savings_goal',
+      'irregular_savings',
+    ];
+
+    const events: TestEvent[] = tipIds.flatMap((tipId) => [
+      { name: 'coach.tip.triggered', payload: { tipId } },
+      { name: 'coach.tip.follow_up_action_taken', payload: { tipId } },
+    ]);
+
+    const progress = moneyAmbientCoachTrack.steps.map((step) => ({
+      id: step.id,
+      status: 'PENDING' as 'PENDING' | 'COMPLETED',
+    }));
+
+    events.forEach((event) => {
+      moneyAmbientCoachTrack.steps.forEach((stepSpec, index) => {
+        const step = progress[index];
+        if (!step || step.status === 'COMPLETED') return;
+        if (stepSpec.completion.kind !== 'event') return;
+        if (stepSpec.completion.eventName !== event.name) return;
+        if (
+          !matchesFilter(
+            stepSpec.completion.payloadFilter,
+            event.payload as Record<string, unknown> | undefined
+          )
+        ) {
+          return;
+        }
+        step.status = 'COMPLETED';
+      });
+    });
+
+    expect(progress.every((s) => s.status === 'COMPLETED')).toBeTrue();
+  });
+});

package/src/track.ts

@@ -0,0 +1,74 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+const makeTipStep = (
+  id: string,
+  tipId: string,
+  description: string
+): LearningJourneyTrackSpec['steps'][number] => ({
+  id,
+  title: `Resolve tip: ${tipId}`,
+  description,
+  completion: {
+    kind: 'event',
+    eventName: 'coach.tip.follow_up_action_taken',
+    payloadFilter: { tipId },
+  },
+  xpReward: 20,
+  metadata: { tipId },
+});
+
+export const moneyAmbientCoachTrack: LearningJourneyTrackSpec = {
+  id: 'money_ambient_coach',
+  name: 'Ambient Coach — Money',
+  description:
+    'Subtle coaching for money patterns (cash buffer, goals, saving rhythm).',
+  targetUserSegment: 'money_user',
+  totalXp: 60,
+  steps: [
+    makeTipStep(
+      'cash_buffer_too_high',
+      'cash_buffer_too_high',
+      'Suggest sweeping excess cash into goals.'
+    ),
+    makeTipStep(
+      'no_savings_goal',
+      'no_savings_goal',
+      'Prompt setting a first savings goal.'
+    ),
+    makeTipStep(
+      'irregular_savings',
+      'irregular_savings',
+      'Recommend recurring saves after irregular deposits.'
+    ),
+  ],
+};
+
+export const colivingAmbientCoachTrack: LearningJourneyTrackSpec = {
+  id: 'coliving_ambient_coach',
+  name: 'Ambient Coach — Coliving',
+  description: 'Contextual tips for healthy coliving habits.',
+  targetUserSegment: 'coliving',
+  totalXp: 60,
+  steps: [
+    makeTipStep(
+      'noise_late_evening',
+      'noise_late_evening',
+      'Suggest updating quiet hours to reduce evening noise.'
+    ),
+    makeTipStep(
+      'guest_frequency_high',
+      'guest_frequency_high',
+      'Set guest frequency expectations for the house.'
+    ),
+    makeTipStep(
+      'shared_space_conflicts',
+      'shared_space_conflicts',
+      'Offer a shared-space checklist to reduce conflicts.'
+    ),
+  ],
+};
+
+export const ambientCoachTracks: LearningJourneyTrackSpec[] = [
+  moneyAmbientCoachTrack,
+  colivingAmbientCoachTrack,
+];

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}