app development context

CONTEXT.md

@@ -0,0 +1,111 @@
+# Mastermind
+
+Mastermind is a personal, local-first macOS assistant that turns activity on the user's Mac into inspectable context for grounded assistance.
+
+## Product
+
+**Mastermind**:
+The personal assistant product and the only target product name.
+_Avoid_: Cheating Daddy, Mastermind Native, AI helper
+
+**Local Profile**:
+The local identity whose sources, knowledge, history, and policies belong to the current macOS user. A future cloud account may authenticate services but does not own the Local Profile.
+_Avoid_: User account, cloud profile
+
+**Companion Island**:
+Mastermind's normally hidden interaction surface at the top center of the primary display. Hover reveals a capsule and clicking expands it into the assistant interface.
+_Avoid_: Overlay, HUD, Dynamic Island, floating window
+
+## Context acquisition
+
+**Source**:
+A configured origin from which Mastermind may observe context, such as a workspace, calendar, screen, audio stream, or terminal integration.
+_Avoid_: Connector, data source
+
+**Collector**:
+The independently operating part of Mastermind that observes one kind of Source and emits Observations.
+_Avoid_: Capture mode, watcher, sensor
+
+**Observation**:
+Immutable, time-stamped evidence emitted by a Collector about a Source. An Observation is evidence, not a claim that Mastermind treats as true.
+_Avoid_: Event, Fact, memory
+
+**Gap**:
+An explicit interval in which an enabled Collector could not produce usable Observations.
+_Avoid_: Missing memory, silent failure
+
+## Knowledge
+
+**Context Graph**:
+The Local Profile's structured, time-aware representation of entities, relationships, Observations, Assertions, and Facts.
+_Avoid_: Memory, activity database, transcript archive
+
+**Assertion**:
+A time-scoped claim inferred from one or more Observations, with confidence and Provenance. Assertions may conflict and expire.
+_Avoid_: Fact, summary
+
+**Fact**:
+An Assertion explicitly confirmed or corrected by the user. Facts remain until the user removes or supersedes them.
+_Avoid_: High-confidence inference, model output
+
+**Provenance**:
+The trace from an Assertion, Fact, summary, or answer back to the Source and Observations that support it.
+_Avoid_: Citation text, model reasoning
+
+**Person**:
+A human relevant to the Local Profile's work.
+_Avoid_: Speaker, participant record
+
+**Project**:
+An ongoing effort directed toward an outcome. A Project may span multiple Workspaces, Tasks, Events, Meetings, and Artifacts.
+_Avoid_: Repository, folder, session
+
+**Task**:
+An actionable unit of work represented by an external source. Mastermind understands Tasks but is not their system of record.
+_Avoid_: Action Proposal, reminder
+
+**Event**:
+A time-bounded occurrence meaningful to the user's work, such as a deadline or milestone.
+_Avoid_: Observation, log entry
+
+**Meeting**:
+A human interaction inferred from calendar, application, and audio Observations. Audio channel roles do not establish a participant's identity.
+_Avoid_: Assistant Session, Conversation
+
+**Artifact**:
+A persistent work product or reference relevant to a Project, such as a document or source file.
+_Avoid_: Observation, screen frame
+
+**Workspace**:
+An explicitly connected directory or repository that provides Artifacts and project context.
+_Avoid_: Project, home directory
+
+## Assistance and trust
+
+**Assistant Session**:
+A bounded text interaction in the Companion Island using one selected Provider. Assistant Sessions are distinct from Meetings.
+_Avoid_: Conversation, capture session, chat memory
+
+**Provider**:
+An inference service used to generate assistance. A Local Provider runs on the same Mac; a Cloud Provider receives data outside the Mac.
+_Avoid_: Model, agent, sidecar
+
+**Provider Context Permission**:
+The user's explicit permission for a Cloud Provider to receive locally selected context. Permission is denied by default and can be revoked for future requests.
+_Avoid_: Source Policy, blanket consent
+
+**Context Receipt**:
+The inspectable record attached to an answer that identifies its supporting context, Provider, and any external data transfer.
+_Avoid_: Citation, Activity Log
+
+**Activity Log**:
+The local audit trail of Collector lifecycle, permission failures, gaps, and Provider requests without captured content.
+_Avoid_: Assistant History, transcript
+
+**Assistant History**:
+The persistent local record of Assistant Sessions. It is separate from the Context Graph and Activity Log.
+_Avoid_: Memory, Context Graph
+
+**Action Proposal**:
+A plan or draft suggested by Mastermind for the user to carry out. It does not authorize Mastermind to act on the Mac.
+_Avoid_: Tool call, agent action, Task