tutti/docs/conventions/feature-flags.md

Feature Flags

Feature flags in Tutti are pure config distribution: durable storage in daemon preferences, push to clients over the eventstream, a key registry, and a query helper. The infrastructure is semantics-free — it stores and distributes map[string]bool and nothing more. Each feature owns what "off" means; that logic never belongs to the flag infrastructure.

Taxonomy

• Capability flags gate daemon-enforced behavior (writes, orchestration, runtime operations). The daemon must enforce them server-side so toggling the UI cannot bypass the gate. Query them through the daemon registry helper, never by poking the raw map.
• UI-preference flags only show or hide renderer surfaces. The renderer catalog is sufficient; no daemon enforcement is required.

A flag can start as UI-preference and gain daemon enforcement later; keep the same key when that happens.

lab.connectors is a capability flag whose owning surfaces span renderer settings, daemon composition, and daemon-projected Composer Options. The daemon reads it fail-closed during startup. When it is off, the Connector market, runtime, MCP gateway, Agent runtime projection, and tutti connector command provider are not constructed; consequently Connector policy is not injected into Agent system prompts. Existing installed state remains on disk. Changing the flag takes effect for daemon-owned Connector capabilities after the daemon restarts. Renderer off semantics also remove the Connectors settings entry, connector setup deep links, and connector entries from the Agent composer, and the AgentGUI footer uses Tutti Mode as that slot's fallback. Renderer projections must filter cached connector palette rows while the daemon-backed Composer Options reread is in flight.

Key contract

The daemon registry is the key contract:

• Go: services/tuttid/biz/preferences/lab_flags.go
• Renderer mirror: apps/desktop/src/shared/featureFlags/catalog.ts

Both must carry identical keys and defaults. When adding, renaming, or removing a flag, change both sides in the same change. Storage and push are already generic (DesktopPreferences.FeatureFlags, NormalizeDesktopFeatureFlags, preferences eventstream updates), so a new flag only needs registry entries and copy.

When a feature graduates, remove its registry entries and every owning-feature gate in the same change. Historical stored values may remain in generic preferences for compatibility, but graduated features must not consult them; this makes the feature available to existing profiles even when their old value was false.

Resolution rule on both sides: a stored value wins; absent keys fall back to the registry default; absent unregistered keys resolve to false (IsLabFlagEnabled in Go, isFeatureEnabled in TS).

Defaults and off semantics

• Defaults are fail-closed: every Lab flag defaults to false. A flag that must default on needs an explicit product decision recorded in the PR.
• Recommended default-off semantics (guidance, not a mandate): while a flag is off, new writes are rejected or hidden, but existing data and already running behavior are left unaffected. The owning feature decides and documents its exact semantics.

Naming

• lab.* for Lab experiments surfaced in the Lab settings section.
• Domain-scoped dotted keys for everything else, for example agent.extension.<source> or browser.chromeCookieImport.
• Keys are lowercase camelCase segments joined by dots.

Existing reference pattern

services/tuttid/service/agentextension/manager.go is the existing example of feature-owned semantics: stable sources are enabled by generated product configuration and ignore retired stored activation values, while Early Access sources derive their own keys ("agent.extension."+source.Key) and decide what disabled means (reconcile and stop). New consumers should prefer registry constants and IsLabFlagEnabled over poking the raw map, while keeping their own off and graduation semantics in the owning feature, exactly as the Agent Extension manager does.