Declare a flag
packages/flags/src/registry.ts declares each key, kind, default value and description. FlagKey and FlagValues derive from that registry. Unknown database keys are ignored; a missing override falls back to the code default.
"home.greeting": {
kind: "boolean",
defaultValue: true,
description: "Show the personalized greeting on the home screen.",
}The evaluator applies platform and targeting context to typed rows. Parsing belongs at the database boundary. Clients consume the safe registry/evaluator exports; /repo owns the Drizzle reads and writes and must remain server-only.
Boot and administration
appConfig combines evaluated flags and app-update configuration in one public boot request. Admin flag procedures use the current platform admin guard. Web uses useFlags; native boot reads the same server definitions.
A visibility flag is not a capability or authorization check. billing.web can show navigation only after server providers are configured; ai.assistant and ai.capture (a receipt or voice draft structured by the model, see Expense) also require a model provider. A hidden control never replaces membership or role authorization.
Extend
Add the key in code, use its inferred type, and translate any user-facing labels in every catalog. Test default behavior, absent/disabled overrides and invalid stored values. Keep optional features bootable with their flag off and no provider credentials.