terminology

this is the canonical glossary for the app: one vocabulary shared by the UI copy in lib/l10n/app_en.arb, code identifiers (classes, fields, providers, files), and persisted schemas. user-facing terms win. when a concept gets a user-facing name, code names follow it — not the other way around.

check this file before naming a new identifier, ARB key, table, or user-facing string. if you add or rename a user-facing concept, update this file in the same commit. identifiers marked "legacy" survive only in compat readers, persisted values, and migration code.

canonical terms

user-facing term	code identifier	notes / legacy names
meditation	Meditation, meditation*	the authored practice (any mode). the library is "meditations"
recitation	recitation*	counting practice. legacy: counter, counting
breathing exercise	BreathingExercise, BreathPhase	phases: inhale / hold / exhale / second hold
session	Session, session*	a recorded run (completed/aborted), shown in history
segment	Segment	one step inside a meditation. legacy: TimerSegment
soundscape	Soundscape, soundscape*	ambient/binaural/noise audio, library or per-segment. legacy: backgroundSound, background_sound, ambient
bell	bells*/Bell-adjacent	start/end/inhale/exhale/hold bells
interval	IntervalSettings, interval*	per-segment repeating trigger ("every n seconds/breaths/recitations") shared by one bell and/or one haptic; the unit is implied by the segment mode
sub-segment	SubSegment, SubSegmentCycle	the repeating split of a segment: interval triggers and breathing exercises are both cycles of parts with per-boundary bells/haptics/prompts
binaural beat	BinauralBeat
generated soundscape	GeneratedSoundscape, generatedSoundscape*	a synthesized soundscape (drone, pulse, chimes) the user shapes in the library. its layers are "drone", "pulse", and "chimes" in the UI; the synth internals call them bed, pulse, and events
background	Background*, ImageBackground, ColorPreset	visual only — never audio
image / color	ImageBackground, ColorPreset	the two background kinds; UI says "image"/"color"
reminder	Reminder	the scheduled-notification entity. legacy: NotificationProfile
notification	NotificationService, FlutterLocalNotifications*, foregroundNotification*	the OS-level mechanism only — never the entity
prompt	PromptContent, TextPrompt, AudioPrompt, ListItem	audio-list members are "audio prompts"
list / audio list	AppList, ListKind{text,audio}	legacy: prompt_list, quote_list
tag	Tag, tags*
favorite	favorite, setFavorite	pins a meditation to the top of the library list; stored on meditations.favorite and synced
sort order	MeditationSortOrder, meditationListSort*	the meditation library's ordering; persisted as the meditation_list_sort settings key. "recently used" reads meditations.last_used_at, stamped on session start — device-local, never synced or exported
mood / mood preset	MoodPresets, MoodSelector	emoji strings; pre-/post-session
journal	journal, preJournal	free-text; pre-/post-session
check in	SessionCheckIn	the pre/post mood+journal dialogs ("check in" / "how was it?"). legacy: SessionPromptResult
parting words	partingWords*, parting_words_sync_id, partingWordsListSyncId	a short phrase shown on the session-complete screen, drawn from a text list. the built-in list is builtin:parting_words ("default parting words"); meditations override it by list syncId
streak	streak*
goal	PracticeGoals, GoalKind, GoalProgress, goal*	a daily/weekly target for minutes, sessions, or recitations; persisted as the practice_goals settings key and synced
history / stats / insights	history*, SessionStats, insights*	the insights tab hosts the history, journal, and stats sub-screens
player	*Player*	meditation player, recitation player
easy mode	easyMode*, EasyMode*
quick session	quickSession (l10n only)	unnamed session fallback label
silence phone	SilencePhoneService	implemented via Android do-not-disturb. legacy: DndService
system volume	SystemVolumeService, systemVolume	Android media volume applied during a session; the previous level is restored when it ends
screen behavior	ScreenBehavior	keep on / allow timeout / turn off. legacy: keepScreenOn
visualizer	VisualizerStyle, *BreathingVisualizer	styles: dot / tree / wave / circle / starfield / dotted sphere
accent color	AppAccentColor	app-wide accent (fed to ColorScheme.fromSeed). the per-meditation one is colorSeed. legacy key: seed_color
color seed	colorSeed	per-meditation theme seed
count direction	CountDirection	count up / count down
countdown	countdown*	seconds before a session starts
haptics	Haptic*, haptic*	patterns + intensity
text-to-speech	tts*, Tts*	"tts" stays in code (matches plugin names); UI copy says "text-to-speech"
keep screen on	—	superseded by "screen behavior"; legacy only
open-ended	openEnded*	segment/session with no fixed end
theme / appearance	theme*, UiPreferences	theme mode, font scale, compact layout, true black dark mode
settings	settings*, SettingsRepository
welcome tour	WelcomeTour*, welcome*, hasSeenWelcome	first-launch tour at /welcome, replayable from settings; persisted via the has_seen_welcome settings key (device-local, not synced)
help	HelpScreen, HelpSection, HelpContentService, help*	in-app reader for the bundled docs/user-guide/ markdown at /help
backup & sync	backupSync*	local / webdav / watch providers
health sync	health*, HealthSyncTarget
watch	watch*, syncToWatch, WatchStatus	the generic paired-watch concept
wear	wear*, Wear*, main_wear.dart, wear flavor	Wear OS platform code only — see below
notification channel	"mindfulness reminders"	Android channel names say "reminders"

modes

a meditation has one of three modes, and so does each segment. the canonical vocabulary is meditation / recitation / breathing — the same words used in the easy-mode titles, stats, and Wear screens.

• code uses a single enum MeditationMode { meditation, recitation, breathing } for both levels (the old SegmentMode was a duplicate and is gone).
• wire values 'timer' and 'counter' still appear in persisted data; the converter reads them as meditation and recitation.
• do not reintroduce duration, counting, timer, or counter as user-facing mode names.

wear vs watch

"wear" names the Wear OS platform surface; "watch" names the generic concept of a paired watch. the distinction matters because watchOS support is planned.

• wear*, Wear*, main_wear.dart, the wear flavor, WearApp, WearScaffold, WearRotary*, WearAmbientShell, WearOngoingService — code that runs on or targets Wear OS specifically.
• watch*, syncToWatch, WatchStatusLine, "watch sync", "paired watch", "sync to watch" — the device-concept in shared and phone-side code and all user-facing copy.
• DataLayer* stays: it is the name of Google's Wear OS API.
• Session.originDevice stores platform ids ('phone', 'wear'); watchOS will add 'watchos'. these are persisted values, not terminology.

reminder vs notification

a reminder is the user-created entity (title, message source, schedule, tap action, linked meditation). a notification is the OS object the scheduler posts when a reminder fires. code that operates on the entity uses reminder* (Reminder, RemindersRepository, ReminderScheduler, ReminderTapAction); code that wraps the platform API keeps notification* (NotificationService, FlutterLocalNotificationsService, foregroundNotification*, permission handling).

persisted names never change

renaming a Dart identifier is free; renaming a stored string is a migration. the following are frozen forever — change the Dart name if needed, keep the stored value:

• SQLite table and column names (timer_segments, notification_profiles, soundscapes, custom_text, origin_device, …). a renamed @DriftDatabase table class keeps its SQL name via @override String get tableName.
• settings keys in settings (seed_color, easy_mode_settings, …).
• JSON keys inside settings blobs, sessions.easyModeSettingsJson, Meditation.toJson() / .med manifests, sync payloads, tombstone entity types, and Wear data-layer paths.
• enum wire values ('timer', 'counter', 'custom', 'quoteList', 'other', 'wear', …). renamed enums keep a converter that reads the old value (dual-read, write the canonical value).
• built-in sound names and sync ids ('builtin:noise_white', the builtin: map in built_in_soundscapes.dart, the builtin:generated_* ids in BuiltInGeneratedSoundscape) and asset paths under assets/ (assets/sounds/music/ predates the "soundscape" term).
• the json keys of a generated soundscape's parameters column (GeneratedSoundscapeConfig.toJson), the MusicalScale value names stored in it, the 'generated' sound source value on meditation_soundscapes rows, and generatedSoundIdBase (easy-mode settings store generated soundscape ids offset by it).
• origin_device values, health-sync target ids, Android notification channel ids.

legacy names you will still see

migration code refers to historical schema names — quote_lists, quotes, prompt_lists, prompts, background_sounds, meditation_backgrounds, keepScreenOn, MessageSource value 'quoteList'. these appear only inside AppDatabase.onUpgrade (app_database_migrations.dart), migration helpers, and compat readers. never rename them: they describe what old databases actually contain. the matching comment in app_database_migrations.dart repeats this rule.

copy rules

• all user-facing English goes through app_en.arb and stays lowercase.
• documentation counts as user-facing for casing: docs/ and the root markdown files are lowercase prose, except proper nouns (Wear OS, GitLab) and code identifiers, which keep their canonical casing. PROJECT_PLAN.md is historical and exempt.
• "use app default" is the one true default-override phrasing — for settings that actually have a configurable default. the breathing exercise picker is not one of them: there is no app-default exercise, so the picker always shows a concrete exercise and an unselected segment falls back to box breathing.
• switches read "on"/"off"; "enabled"/"disabled" is for prose and status text.
• don't land an ARB key without a call site — dead keys are how the old "prompt list" and "keep screen on" vocabulary survived its own removal.