5.2.1

Aug 01, 2026 · 3 packages · 14 unique changes · 4 release entries

appsbundlesBreaking changes

This release affects the solutions family.

Run contractspec connect adoption resolve --family solutions to see how it impacts your project.

Release summaries

builder-local-onboarding-api-resolution
Fix Builder local onboarding so setup writes usable control-plane defaults and the CLI resolves Builder API settings from workspace config.
maintainer
Builder-local setup now writes control-plane API defaults, doctor checks all Builder presets for missing auth, and the Builder CLI reads `.contractsrc.json` before falling back to the default hosted API.
integrator
Fresh `contractspec init --preset builder-local` workspaces now include the Builder API base URL in both `.contractsrc.json` and VS Code settings, while older local-only configs still work through the hosted API fallback.
can-help-capability-discovery
Add the `can-help` offline capability-discovery surface (CLI command + workspace service) over a two-tier capability corpus.
maintainer
bundle.workspace ships a new `canHelp` service (buildCapabilityCorpus, queryCanHelp, rankCapabilities, vectorize/cosine) that composes the adoption catalog and a local workspace overlay into a two-tier capability corpus and ranks free-text intents with a model-free offline term-vector blended with lexical tag overlap, returning have-it/can-help/gap verdicts. The CLI exposes it as `can-help`/`ask`.
integrator
Consumers and agents can call `contractspec can-help "<intent>" --json` (scope all|local|ecosystem, optional --family) to discover whether ContractSpec already provides a capability before reinventing it. Fully offline; no model or network required.
customer
Teams adopting ContractSpec across many verticals get a guided way to find and reuse existing capabilities instead of rebuilding them, improving velocity and consistency.
canonical-release-pipeline
Unify release authoring around guided capsules, canonical generated artifacts, and manifest-backed changelog surfaces.
maintainer
Release preparation now runs through guided `contractspec release prepare` and `contractspec release edit` flows, generated release artifacts become the canonical source of truth, and stable publish automation creates a GitHub Release from patch notes plus attached release artifacts.
customer
The public changelog now renders canonical release summaries, deprecations, migration guidance, and upgrade steps directly from the generated release manifest instead of scraping package changelogs.
integrator
Existing tooling that depended on `contractspec changelog` or on the `@lssm-tech/action.version` changelog side effect must move to `contractspec release prepare` plus `generated/releases/*`.
stabilize-current-release-artifacts
Stabilize release artifact generation so customer-facing release files stay current-release-only and deterministic.
maintainer
Release builds now default to compact current-release artifacts, while full historical output must be requested explicitly with `--scope all`.
integrator
Tooling that needs full changelog history should consume `generated/releases/history/manifest.json`; current release guidance stays under `generated/releases/*`.
customer
Customer-facing release bundles are smaller and avoid repeatedly rewriting old release entries.

Deprecations

- `contractspec changelog generate` is no longer the supported release-authoring flow.
- `contractspec changelog show` is no longer the supported public release surface.

Migration guide

Generate full release history explicitly
Consumers that previously treated `generated/releases/manifest.json` as a full historical changelog should build the history output path.
1. Run `contractspec release build --scope all --output generated/releases/history` before building full changelog surfaces.
2. Keep `generated/releases/*` for current GitHub Release notes, upgrade prompts, and customer AI guidance.
Replace the legacy changelog CLI flow
Required
Stop invoking `contractspec changelog` for release preparation and use `contractspec release prepare`, `contractspec release build`, or `contractspec release brief` instead.
When: When local scripts, docs, or release automation still call the legacy changelog commands.
1. Replace `contractspec changelog generate` and `contractspec changelog show` calls with the new release commands that match the workflow intent.
2. Treat `generated/releases/manifest.json` and `generated/releases/upgrade-manifest.json` as the canonical inputs for downstream changelog and upgrade tooling.
Stop relying on action-version changelog side effects
Required
`@lssm-tech/action.version` no longer runs the generic changelog generator during bump mode.
When: When CI expects the action to emit generic changelog files automatically.
1. Generate canonical release artifacts with the release pipeline instead of expecting generic changelog output from the action.
2. Read release data from `generated/releases/*` rather than from package changelog aggregation.

Upgrade steps

Refresh existing builder-local workspace config when convenient
manual
Existing local-only configs keep working through the hosted API fallback, but rerunning init will persist the new API defaults into workspace config.
Packages: @lssm-tech/bundle.workspace, @lssm-tech/app.cli-contractspec
1. Re-run `contractspec init --preset builder-local` if you want the generated `builder.api.baseUrl` and `builder.api.controlPlaneTokenEnvVar` fields written into `.contractsrc.json`.
2. Set the configured control-plane token environment variable before running `contractspec builder` commands.
Discover ContractSpec capabilities from the CLI
manual
Run `contractspec can-help "<what you want to do>"` (or `contractspec ask ...`) to get a have-it/can-help/gap verdict and the canonical surface to adopt. Add `--json` for agents and CI. No configuration required.
Packages: @lssm-tech/bundle.workspace, @lssm-tech/app.cli-contractspec
Keep current release artifacts compact
manual
Use the default release build for current release communication and the explicit history scope only when a full changelog is required.
Packages: @lssm-tech/bundle.workspace, @lssm-tech/app.cli-contractspec, @lssm-tech/app.web-landing, contractspec
1. Run `bun run release:build` for the current release bundle.
2. Run `bun packages/apps/cli-contractspec/src/cli.ts release check --strict --baseline main` after regenerating artifacts.
3. Use `--scope all --output generated/releases/history` for website changelog history builds.
Use guided release authoring
manual
Create and revise release metadata through `contractspec release prepare` and `contractspec release edit` instead of editing capsules by hand.
Packages: @lssm-tech/bundle.workspace, @lssm-tech/app.cli-contractspec, @lssm-tech/action.version, @lssm-tech/app.web-landing
1. Run `contractspec release prepare` for new published-package release work.
2. Run `contractspec release edit <slug>` to revise an existing release entry safely.
Publish canonical release artifacts
assisted
Stable release automation now uploads the release manifest, upgrade manifest, customer guide, and agent prompts, and uses generated patch notes as the GitHub Release body.
Packages: @lssm-tech/bundle.workspace, @lssm-tech/app.cli-contractspec, @lssm-tech/action.version, @lssm-tech/app.web-landing
1. Review `generated/releases/*` as part of release preparation.
2. Use the attached release artifacts instead of scraping package CHANGELOG files or generic changelog JSON.

Unique release changes

- `@lssm-tech/action.version` no longer runs the generic changelog generator during bump mode.
3 packages · 3 occurrences
- `contractspec changelog generate` is no longer the supported release-authoring flow.
3 packages · 3 occurrences
- `contractspec changelog show` is no longer the supported public release surface.
3 packages · 3 occurrences
- Consumers that previously treated `generated/releases/manifest.json` as a full historical changelog should build the history output path.
3 packages · 3 occurrences
- Create and revise release metadata through `contractspec release prepare` and `contractspec release edit` instead of editing capsules by hand.
3 packages · 3 occurrences
- Stabilize release artifact generation so customer-facing release files stay current-release-only and deterministic.
3 packages · 3 occurrences
- Stable release automation now uploads the release manifest, upgrade manifest, customer guide, and agent prompts, and uses generated patch notes as the GitHub Release body.
3 packages · 3 occurrences
- Stop invoking `contractspec changelog` for release preparation and use `contractspec release prepare`, `contractspec release build`, or `contractspec release brief` instead.
3 packages · 3 occurrences
- Unify release authoring around guided capsules, canonical generated artifacts, and manifest-backed changelog surfaces.
3 packages · 3 occurrences
- Use the default release build for current release communication and the explicit history scope only when a full changelog is required.
3 packages · 3 occurrences
- Add the `can-help` offline capability-discovery surface (CLI command + workspace service) over a two-tier capability corpus.
2 packages · 2 occurrences
- Existing local-only configs keep working through the hosted API fallback, but rerunning init will persist the new API defaults into workspace config.
2 packages · 2 occurrences
- Fix Builder local onboarding so setup writes usable control-plane defaults and the CLI resolves Builder API settings from workspace config.
2 packages · 2 occurrences
- Run `contractspec can-help "<what you want to do>"` (or `contractspec ask ...`) to get a have-it/can-help/gap verdict and the canonical surface to adopt. Add `--json` for agents and CI. No configuration required.
2 packages · 2 occurrences

Impacted packages

@lssm-tech/app.cli-contractspec
Layer: apps · 7 changes
@lssm-tech/app.web-landing
Layer: apps · 7 changes
@lssm-tech/bundle.workspace
Layer: bundles · 7 changes