feat: Implement history tracking with new CLI commands for viewing past transcripts and usage statistics.

docs/HISTORY_AND_STATS.md

@@ -0,0 +1,43 @@
+# History and Stats Implementation Plan
+
+This document outlines the design and implementation of the `history` and `stats` features in Toak.
+
+## Data Storage
+All transcriptions will be stored in a JSON Lines (`.jsonl`) file located at `~/.local/share/toak/history.jsonl`.
+Since Toak uses Native AOT and JSON serialization needs source generation, we'll keep the model simple.
+
+**Entry Model:**
+```json
+{
+  "Timestamp": "2025-01-15T09:23:00Z",
+  "RawTranscript": "hello world",
+  "RefinedText": "Hello world.",
+  "SkillName": "Professional",     // null if default type/script
+  "DurationMs": 1500               // time taken for STT + LLM
+}
+```
+
+## `toak history` Command
+Provides access to past dictations.
+
+- `toak history` - Shows the last 10 entries.
+- `toak history -n <count>` - Shows the last `<count>` entries.
+- `toak history --grep <pattern>` - Filters the history entries matching the given keyword in the RefinedText (case-insensitive).
+- `toak history --export <file>` - Writes the output as a Markdown file.
+- `toak history --shred` - Deletes the `history.jsonl` file entirely.
+
+## `toak stats` Command
+Reads the `history.jsonl` file and outputs usage analytics using `Spectre.Console`.
+
+**Metrics:**
+- Total recording count
+- Total processing duration (sum of `DurationMs`)
+- Average processing duration
+- Most active day
+- Most frequently used skill (if any)
+
+## Architecture Changes
+1. **`HistoryManager.cs`**: Handles thread-safe appending `HistoryEntry` to the `.jsonl` file, reading, and clearing.
+2. **`DaemonService.cs`**: Calls `HistoryManager.SaveEntry` during the `ProcessStopRecordingAsync` method after text is finalized.
+3. **`HistoryCommand.cs` & `StatsCommand.cs`**: CLI command definitions.
+4. **`AppJsonSerializerContext.cs`**: Needs `[JsonSerializable(typeof(HistoryEntry))]`.

docs/STRUCTURE.md

@@ -23,13 +23,17 @@ Toak/
 │   ├── ConfigUpdaterCommand.cs # Direct configuration modifications
 │   ├── ShowCommand.cs       # Display current configuration
 │   ├── SkillCommand.cs      # CLI controller for discovering and adding Dynamic JSON Skills
-│   └── LatencyTestCommand.cs # Benchmark tool for API calls
+│   ├── LatencyTestCommand.cs # Benchmark tool for API calls
+│   ├── HistoryCommand.cs    # CLI interface to query, export, or shred past transcripts
+│   └── StatsCommand.cs      # CLI interface to calculate analytics from history
 ├── Configuration/
 │   ├── ConfigManager.cs     # Loads and saves JSON configuration from the user's home folder
 │   └── ToakConfig.cs        # Data model for user preferences
 ├── Core/
 │   ├── DaemonService.cs     # The background daemon maintaining the socket server and handling states
 │   ├── Logger.cs            # Logging utility (verbose logging)
+│   ├── HistoryManager.cs    # Manages appending and reading the local history.jsonl
+│   ├── HistoryEntry.cs      # The data model for transcription history
 │   ├── PromptBuilder.cs     # Constructs the system prompts for the LLM based on user settings
 │   ├── StateTracker.cs      # Tracks the current application state (e.g. is recording active?)
 │   └── Skills/              # Data-driven JSON skill integrations