Experimental Features

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.

Config entries under an experiment are settings for that experiment, not nested experiments or independent feature flags. Keep them stored with the parent experiment and gate their runtime effect on the parent experiment being enabled.

Supported config controls:

• boolean: switch with a boolean default
• select: fixed string options with a default
• number: default plus optional min/max/step
• text: default plus optional placeholder; never for secrets

Use getExperiment(id) or useExperiment(id) for callers. When an experiment is disabled, keep config stored but gate behavior as disabled.

Internal-Only Experiments

Internal-only experiments need build gates at every layer they touch:

• Add a BuildFeature resolved from a positive-opt-in VITE_* variable in src/shared/profile/buildProfile.ts, and declare the variable in src/env.d.ts.
• Map the experiment id to that feature in BUILD_FEATURE_GATED_EXPERIMENTS.
• If the experiment has backing Tauri commands, gate them behind a matching block-* Cargo feature and map the VITE_* variable in scripts/block-feature-gates.sh; drift-guard tests in scripts/release/tests/release-scripts.test.mjs enforce this.
• Set the gate to 0 in the public env in .github/workflows/release.yml.

Registry-level hiding stops stale per-user localStorage overrides from re-enabling internal surfaces in consumer builds (issue 168).

Storage Contract

Experiment preferences live in localStorage under goose:experimental-features:

{
  "version": 2,
  "autoEnable": false,
  "experiments": {
    "experiment-id": {
      "enabled": false,
      "config": {}
    }
  }
}

• Treat version as real schema state. On newer stored versions, abort writes instead of overwriting; on older versions, migrate explicitly or discard.
• Store autoEnable as the global default provider. Store enabled only for explicit per-experiment overrides; clearing enabled returns that experiment to auto behavior and must preserve config.
• Keep config under the parent experiment. Do not migrate config keys into separate experiment ids or apply auto-enable behavior to individual settings.
• Preserve unknown experiment ids when writing so branch switches do not erase local choices.
• Write only the touched experiment/key and re-read latest storage immediately before saving to reduce cross-window clobbering.
• Setters return boolean; callers must surface failed writes to users.
• Use useSyncExternalStore for React subscriptions. Memoize only the current raw storage value per registry/id; do not retain historical snapshot keys.