experimental-features

name	experimental-features
description	Use when adding, reviewing, configuring, graduating, or removing Berd experiments.

Experimental Features

Use experiments for opt-in, user-local in-progress Berd UI or workflow behavior. Do not use experiments for secrets, credentials, backend authority, packaged policy, or app state that should survive graduation as a normal preference.

When To Use Experiments

• An individual user opts into unstable UI or workflow behavior.
• Stable behavior can remain the default path.
• Config is small, non-sensitive, typed, and user-editable.
• The feature can be graduated or removed later.

When To Use distro.json

Use distro.json for packaged build policy and startup defaults, especially when the Tauri shell or sidecar needs bundled resources/config.

Good distro fits include providerAllowlist, kgoose, featureToggles.costTracking, bundled config.yaml, bin/, skills/, and agents/.

Do not use distro.json for normal app state, user preferences, dynamic runtime switches, ACP-backed data, or per-user experiments.

Registry Shape

Add experiments only in src/features/experiments/experimentDefinitions.ts.

Each definition needs:

• id: stable kebab-case string
• titleKey and descriptionKey: settings i18n keys
• config: optional typed controls

Experiments without a manual per-experiment override follow the global autoEnable preference. That preference defaults on in dev builds and off in production builds. Users can force an experiment on/off or reset it back to auto from settings.