docs: add domain glossary (CONTEXT.md)

[infiniV]

What

Adds CONTEXT.md, the VoiceFlow domain glossary. It defines the canonical "Recording" terminology (the meeting-notes feature) used across the DB, RPC methods, services, and logs, and documents the deliberate "Recording" in code / "Meeting" in the UI split.

Why

docs/adr/0002-recording-vs-meeting-naming.md already references this file ("...See CONTEXT.md"), but it was never committed, leaving a dangling reference. Reported by an external contributor in #40.

Notes

• Single new file, no code changes.
• Ships with the next release.

Closes #40.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new CONTEXT.md file establishing a domain glossary for the VoiceFlow project. It defines canonical terminology for "Recording" — covering creation flows, system-wide naming touchpoints (DB, RPC, services, filesystem, logs), the UI display label ("Meetings") versus internal identifier ("recording"), and how Recordings differ from "History".

Changes

VoiceFlow Domain Glossary

Layer / File(s)	Summary
VoiceFlow domain glossary CONTEXT.md	Defines the canonical "Recording" term including live capture vs import creation flows, DB/RPC/service/filesystem/log touchpoints, "Meetings" UI label vs "recording" internal naming, and distinction from "History".

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A rabbit hopped in with a scroll so neat,
"Here are the words that make our system complete!"
A Recording is born — live captured or imported with care,
Called 'Meetings' up front, but 'recording' back there.
The glossary is planted, the context is grown 🌱

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add domain glossary (CONTEXT.md)' clearly and concisely describes the main change—adding the missing CONTEXT.md documentation file.
Linked Issues check	✅ Passed	The PR directly addresses issue #40 by adding the missing CONTEXT.md file that was referenced in existing ADR documentation but never pushed to the repository.
Out of Scope Changes check	✅ Passed	The PR contains only the addition of CONTEXT.md file, which is directly within scope of the linked issue #40 requirement to add the missing glossary file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/add-context-glossary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

CONTEXT.md (1)

18-20: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Consider adding event naming convention to system touchpoints.

The enumeration of "system touchpoints" (DB, RPC, services, filesystem, logs) omits a critical contract: the event naming pattern. According to src-pyloid/services/recording/controller.py:738-762, Recording lifecycle events follow the pattern recording-<kind>-complete (e.g., recording-transcribe-complete) and are emitted for all terminal outcomes. This is explicitly documented as a contract that "the frontend depends on."

Including this pattern in the glossary would align the documentation with the actual domain boundaries and help new contributors understand how Recordings integrate across the system.

💡 Suggested addition to line 18-20

 A Recording is the entity in the DB (`recordings` table), in RPC methods (`recordings_*`),
-in services (`RecordingService`, `RecordingsRepository`), in the audio folder
-(`~/.VoiceFlow/recordings/`), and in logs (`domain=recording`).
+in services (`RecordingService`, `RecordingsRepository`), in the audio folder
+(`~/.VoiceFlow/recordings/`), in logs (`domain=recording`), and in events
+(`recording-<kind>-complete`, e.g., `recording-transcribe-complete`).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTEXT.md` around lines 18 - 20, The CONTEXT.md documentation lists system
touchpoints for Recording entities (DB, RPC, services, filesystem, logs) but
omits the event naming convention which is a critical contract. According to the
actual implementation, Recording lifecycle events follow the pattern
`recording-<kind>-complete` for all terminal outcomes and the frontend depends
on this contract. Add the event naming convention as a documented system
touchpoint in the Recording glossary entry to align the documentation with the
actual domain boundaries and clearly communicate to new contributors how
Recording events are named and emitted across the system.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@CONTEXT.md`:
- Around line 18-20: The CONTEXT.md documentation lists system touchpoints for
Recording entities (DB, RPC, services, filesystem, logs) but omits the event
naming convention which is a critical contract. According to the actual
implementation, Recording lifecycle events follow the pattern
`recording-<kind>-complete` for all terminal outcomes and the frontend depends
on this contract. Add the event naming convention as a documented system
touchpoint in the Recording glossary entry to align the documentation with the
actual domain boundaries and clearly communicate to new contributors how
Recording events are named and emitted across the system.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: acea6987-6dc2-475d-bcb7-557be15b055d

📥 Commits

Reviewing files that changed from the base of the PR and between f63609a and 020c059.

📒 Files selected for processing (1)

• CONTEXT.md