4.0.8

Apr 29, 2026 · 8 packages · 14 unique changes · 5 release entries

appsbundleslibsmodulesBreaking changes

Release summaries

quiet-learning-thread
Redesign the learning system around the adaptive journey runtime and repair shared learning sandbox presentation wiring.
maintainer
The learning stack now uses the adaptive `learning.journey.*` runtime and the sandbox resolves shared learning registry presentations through `@contractspec/module.examples`.
integrator
Integrators must adopt the new adaptive journey contracts/types and can rely on shared learning sandbox presentations resolving correctly for the supported `learning-journey-*` templates.
customer
Learning journey demos now follow the adaptive branch-aware runtime, and the public sandbox no longer fails when loading the shared learning presentation descriptors for supported learning templates.
restore-web-landing-examples
Restore the public web-landing templates and examples surfaces so non-internal examples render in the templates catalog, docs routes, sitemap, and sandbox fallback previews.
maintainer
Example discovery now has explicit non-internal registry helpers, and web-landing consumes those helpers for templates, docs route generation, sitemap entries, and sandbox fallback behavior.
integrator
Integrators can use the new `@contractspec/module.examples` helpers to list discoverable examples and template examples without reimplementing visibility and surface filtering.
customer
The public website now shows the full non-internal template catalog, generates example docs for experimental examples, and keeps sandbox template pages useful even when a bespoke interactive preview is unavailable.
support-bot-reliability-threshold-cleanup
Harden support-bot runtime validation, align responder prompts with i18n, and replace the overloaded support-bot threshold config with explicit semantics.
maintainer
Support-bot now validates tool inputs and classifier LLM overrides more defensively, and its responder prompt/catalog wiring is aligned and covered by focused unit tests.
integrator
`defineSupportBot` no longer accepts `autoEscalateThreshold`; integrators must migrate to the explicit `thresholds` object and can now pass `review` directly.
unbundle-examples-runtime
Split example discovery from rich runtime packages so lightweight consumers no longer install every ContractSpec example.
integrator
`@contractspec/module.examples` root imports now expose catalog metadata only; rich runtime helpers moved to `@contractspec/module.examples/runtime`.
integrator
CLI installs avoid the full example dependency set and can fetch a selected example source on demand with `contractspec examples download <key>`.
unify-example-previews
Unify example preview metadata so templates, docs, sandbox, and mobile preview routes derive preview support from shared example registry data instead of hand-maintained lists.
maintainer
Preview wiring now comes from shared example preview surface helpers, and UI-backed example packages must expose `entrypoints.ui` in their exported `ExampleSpec`.
integrator
Integrators consuming public example metadata can now detect inline-preview capability and fallback preview links through `@contractspec/module.examples`, and every public example now has a first-party `/docs/examples/<key>` route in web-landing.
customer
The public site now provides richer template previews and full docs-example coverage, while the mobile demo exposes every discoverable example through in-app native previews with richer panels for exported sample-data examples.

Migration guide

Move learning integrations to the adaptive journey runtime
Required
Replace the old onboarding-centric learning contracts and local example progress logic with the canonical adaptive `learning.journey.*` runtime.
When: When consuming `@contractspec/module.learning-journey` contracts, track specs, or shared learning example progress helpers.
1. Update contract references from `learning.onboarding.*` to `learning.journey.*`.
2. Replace old onboarding/progress type imports with the new adaptive journey types and projected progress snapshots.
3. Remove any local learning track evaluators or progress stores that duplicate the module runtime.
Align learning template mappings with the shared learning registry
Use the shared learning registry mapping/data helpers so supported learning sandbox templates resolve the shared presentation set consistently.
When: When extending sandbox/template support for additional learning examples.
1. Add the template to the learning registry template map and track lookup helpers.
2. Ensure the template’s presentation list uses the shared `learning.journey.*` keys only when the registry can provide matching data.
3. Register descriptor resolution and markdown rendering in `@contractspec/module.examples`.
Replace the old support-bot threshold field
Required
Migrate `defineSupportBot` calls from the overloaded `autoEscalateThreshold` field to the explicit `thresholds` object.
When: When upgrading code that constructs `@contractspec/lib.support-bot` specs through `defineSupportBot`.
1. Replace `autoEscalateThreshold` with `thresholds.autoResolveMinConfidence` when you mean the auto-response cutoff.
2. Set `thresholds.escalationConfidenceThreshold` when you need a distinct policy escalation cutoff.
3. Move any external review routing into the new top-level `review` field if the spec should expose queue or approval workflow metadata.
Import rich example runtime helpers from the runtime subpath
Required
Replace runtime imports such as `TemplateRuntimeProvider`, `listTemplates`, and inline preview loaders from `@contractspec/module.examples` with `@contractspec/module.examples/runtime`.
Use catalog imports for metadata-only example discovery
Required
Import `listExamples`, `getExample`, `searchExamples`, route helpers, and source metadata from `@contractspec/module.examples/catalog` when runnable example code is not needed.
Declare `entrypoints.ui` for UI-backed example packages
Any published example that exports `./ui` should also advertise that UI surface in its `ExampleSpec` entrypoints so preview tooling can discover it.
When: When adding or updating a published example package with a reusable UI export.
1. Add `ui: './ui'` to the example's `entrypoints` object in `src/example.ts`.
2. Update `scripts/generate-example-registry.ts` if the package needs a non-default preview component export.
3. Regenerate the example registries before publishing.

Upgrade steps

Rebuild learning package release artifacts after upgrading
assisted
The affected learning packages should be rebuilt and revalidated together because the runtime, examples, and sandbox wiring now depend on the same adaptive presentation/runtime surface.
Packages: @contractspec/module.learning-journey, @contractspec/module.examples, @contractspec/example.learning-journey-ambient-coach, @contractspec/example.learning-journey-crm-onboarding, @contractspec/example.learning-journey-duo-drills, @contractspec/example.learning-journey-platform-tour, @contractspec/example.learning-journey-quest-challenges, @contractspec/example.learning-journey-registry, @contractspec/example.learning-journey-studio-onboarding, @contractspec/example.learning-journey-ui-coaching, @contractspec/example.learning-journey-ui-gamified, @contractspec/example.learning-journey-ui-onboarding, @contractspec/example.learning-journey-ui-shared, @contractspec/example.learning-patterns
1. Run package-level build, test, typecheck, and lint checks for the affected learning packages.
2. Regenerate example registry artifacts if `@contractspec/module.examples` dependencies change.
3. Verify at least one supported learning sandbox route renders markdown successfully.
Prefer explicit example discovery helpers
assisted
Consumers that need public web-facing example lists should use the new helpers instead of filtering `listExamples()` manually.
Packages: @contractspec/module.examples, @contractspec/bundle.marketing, @contractspec/bundle.library, @contractspec/app.web-landing
1. Use `listDiscoverableExamples()` for docs and sitemap surfaces that should include non-internal examples with usable public surfaces.
2. Use `listTemplateExamples()` for template catalogs.
3. Keep `listPublicExamples()` only when the narrower `visibility: public` subset is required.
Regenerate preview metadata after adding UI-backed examples
assisted
Keep the generated preview registry aligned with the workspace examples.
Packages: @contractspec/module.examples, @contractspec/bundle.marketing, @contractspec/bundle.library, @contractspec/app.web-landing, @contractspec/app.expo-demo, @contractspec/example.agent-console, @contractspec/example.ai-chat-assistant, @contractspec/example.analytics-dashboard, @contractspec/example.crm-pipeline, @contractspec/example.integration-hub, @contractspec/example.learning-journey-registry, @contractspec/example.marketplace, @contractspec/example.policy-safe-knowledge-assistant, @contractspec/example.saas-boilerplate, @contractspec/example.workflow-system
1. Run `bun scripts/generate-example-registry.ts --write`.
2. Re-run preview tests in `packages/modules/examples`, `packages/bundles/marketing`, and `packages/bundles/library`.
3. Verify `/templates`, `/docs/examples/<key>`, `/sandbox?template=<key>`, mobile `/examples`, compatibility `/examples-preview`, and mobile `example-preview?exampleKey=<key>` render the expected inline, fallback, or native preview action.

Unique release changes

- Any published example that exports `./ui` should also advertise that UI surface in its `ExampleSpec` entrypoints so preview tooling can discover it.
5 packages · 5 occurrences
- Keep the generated preview registry aligned with the workspace examples.
5 packages · 5 occurrences
- Unify example preview metadata so templates, docs, sandbox, and mobile preview routes derive preview support from shared example registry data instead of hand-maintained lists.
5 packages · 5 occurrences
- Consumers that need public web-facing example lists should use the new helpers instead of filtering `listExamples()` manually.
4 packages · 4 occurrences
- Import `listExamples`, `getExample`, `searchExamples`, route helpers, and source metadata from `@contractspec/module.examples/catalog` when runnable example code is not needed.
4 packages · 4 occurrences
- Replace runtime imports such as `TemplateRuntimeProvider`, `listTemplates`, and inline preview loaders from `@contractspec/module.examples` with `@contractspec/module.examples/runtime`.
4 packages · 4 occurrences
- Restore the public web-landing templates and examples surfaces so non-internal examples render in the templates catalog, docs routes, sitemap, and sandbox fallback previews.
4 packages · 4 occurrences
- Split example discovery from rich runtime packages so lightweight consumers no longer install every ContractSpec example.
4 packages · 4 occurrences
- Redesign the learning system around the adaptive journey runtime and repair shared learning sandbox presentation wiring.
2 packages · 2 occurrences
- Replace the old onboarding-centric learning contracts and local example progress logic with the canonical adaptive `learning.journey.*` runtime.
2 packages · 2 occurrences
- The affected learning packages should be rebuilt and revalidated together because the runtime, examples, and sandbox wiring now depend on the same adaptive presentation/runtime surface.
2 packages · 2 occurrences
- Use the shared learning registry mapping/data helpers so supported learning sandbox templates resolve the shared presentation set consistently.
2 packages · 2 occurrences
- Harden support-bot runtime validation, align responder prompts with i18n, and replace the overloaded support-bot threshold config with explicit semantics.
1 packages · 1 occurrences
- Migrate `defineSupportBot` calls from the overloaded `autoEscalateThreshold` field to the explicit `thresholds` object.
1 packages · 1 occurrences

Impacted packages

@contractspec/app.cli-contractspec
Layer: apps · 3 changes
@contractspec/app.expo-demo
Layer: apps · 3 changes
@contractspec/app.web-landing
Layer: apps · 3 changes
@contractspec/bundle.library
Layer: bundles · 3 changes
@contractspec/bundle.marketing
Layer: bundles · 3 changes
@contractspec/lib.support-bot
Layer: libs · 2 changes
@contractspec/module.examples
Layer: modules · 3 changes
@contractspec/module.learning-journey
Layer: modules · 4 changes