Detailed changes
@@ -0,0 +1,24 @@
+# config
+
+The `config` package handles all persistent application state: user configuration, email/contacts/drafts caching, folder caching, and email signatures. All data is stored as JSON files under `~/.config/matcha/`.
+
+## Architecture
+
+This package acts as the data layer for Matcha. It manages:
+
+- **Account configuration** with multi-account support (Gmail, iCloud, custom IMAP/SMTP)
+- **Secure credential storage** via the OS keyring (with automatic migration from plain-text passwords)
+- **Local caches** for emails, contacts, drafts, and folder listings to enable fast startup and offline browsing
+- **Email signatures** stored as plain text
+
+All cache files use JSON serialization with restrictive file permissions (`0600`/`0700`).
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `config.go` | Core configuration types (`Account`, `Config`, `MailingList`) and functions for loading, saving, and managing accounts. Handles IMAP/SMTP server resolution per provider, OS keyring integration, and legacy config migration. |
+| `cache.go` | Email, contacts, and drafts caching. Provides CRUD operations for `EmailCache`, `ContactsCache` (with search and frequency-based ranking), and `DraftsCache` (with save/delete/get operations). |
+| `folder_cache.go` | Caches IMAP folder listings per account and per-folder email metadata. Stores folder names to avoid repeated IMAP `LIST` commands, and caches email headers per folder for fast navigation. |
+| `signature.go` | Loads and saves the user's email signature from `~/.config/matcha/signature.txt`. |
+| `config_test.go` | Unit tests for configuration logic. |
@@ -0,0 +1,56 @@
+# docs
+
+Documentation website built with [Docusaurus](https://docusaurus.io/). Contains user-facing guides, feature documentation, and a blog.
+
+## Architecture
+
+A Docusaurus 3 project that generates a static documentation site. The content is organized into guides (installation, usage, configuration) and feature-specific pages.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `docusaurus.config.ts` | Main Docusaurus configuration (site metadata, theme, plugins). |
+| `sidebars.ts` | Documentation sidebar navigation structure. |
+| `package.json` | Node.js dependencies for building the docs site. |
+| `tsconfig.json` | TypeScript configuration. |
+
+### docs/
+
+Documentation content pages:
+
+| File | Description |
+|------|-------------|
+| `index.md` | Documentation home page. |
+| `installation.md` | Installation guide for all platforms. |
+| `usage.md` | Usage guide and keyboard shortcuts. |
+| `Configuration.md` | Configuration file reference. |
+
+### docs/Features/
+
+Feature-specific documentation:
+
+| File | Description |
+|------|-------------|
+| `ACCOUNTS.md` | Multi-account setup and management. |
+| `ADVANCED.md` | Advanced features (S/MIME, custom servers). |
+| `COMPOSING.md` | Email composition guide. |
+| `CONTACTS.md` | Contact management and autocomplete. |
+| `DRAFTS.md` | Draft saving and restoration. |
+| `EMAIL_MANAGEMENT.md` | Email actions (delete, archive, move). |
+| `Hyperlinks.md` | Terminal hyperlink support. |
+| `Images.md` | Inline image rendering and protocols. |
+| `Themes.md` | Theme customization and custom themes. |
+| `UI.md` | General UI documentation. |
+
+### docs/assets/
+
+Screenshot images used in the documentation pages.
+
+### src/
+
+Custom React components and CSS for the documentation site theme.
+
+### static/
+
+Static assets (logos, images) served directly by the documentation site.
@@ -0,0 +1,15 @@
+# fetcher
+
+The `fetcher` package handles all email retrieval operations over IMAP. It connects to mail servers, fetches email headers and bodies, manages attachments, and supports mailbox operations like delete, archive, and move.
+
+## Architecture
+
+This package is the IMAP client layer for Matcha. It:
+
+- Establishes TLS/STARTTLS connections to IMAP servers based on account configuration
+- Fetches email lists with pagination and per-account filtering (using `FetchEmail` to match relevant messages)
+- Retrieves full email bodies with MIME part traversal (preferring HTML over plain text)
+- Handles attachments including inline images (with CID references) and file attachments
+- Supports S/MIME decryption (opaque and enveloped) and detached signature verification
+- Provides mailbox operations: delete (expunge), archive (move), and folder-to-folder moves
+- Exposes both mailbox-specific and convenience functions (e.g., `FetchEmails` defaults to INBOX)
@@ -0,0 +1,30 @@
+# public
+
+Static website files for the Matcha project landing page. This site is deployed via GitHub Pages using the `.github/workflows/static.yml` workflow.
+
+## Architecture
+
+A simple static HTML/CSS website that serves as the public-facing project page with information about features, installation, and contact details.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `index.html` | Main landing page. |
+| `style.css` | Stylesheet for all pages. |
+| `matcha.flatpakref` | Flatpak package reference for Linux distribution. |
+| `features/index.html` | Features overview page. |
+| `get-started/index.html` | Getting started / installation guide page. |
+| `contact/index.html` | Contact information page. |
+
+### assets/
+
+| File | Description |
+|------|-------------|
+| `demo.gif` | Animated terminal demo. |
+| `logo.png` | Project logo. |
+| `logo-transparent.png` | Logo with transparent background. |
+| `logo.txt` | ASCII text version of the logo. |
+| `favicon.ico` | Browser favicon. |
+| `preview.png` | Social media / link preview image. |
+| `screenshots/` | Directory for generated UI screenshots (populated by CI). |
@@ -0,0 +1,23 @@
+# screenshots
+
+This directory contains tooling for automated terminal UI screenshot generation using [VHS](https://github.com/charmbracelet/vhs), a terminal recording and screenshot tool.
+
+## Architecture
+
+Screenshots are generated through a two-layer system:
+
+1. **Go helper programs** (`cmd/`) that render realistic mock UI views using real Matcha components with fake data
+2. **VHS tape scripts** (`.tape` files) that launch these programs and capture terminal output as images
+
+This pipeline runs in CI via the `.github/workflows/screenshots.yml` workflow to keep documentation screenshots up-to-date automatically.
+
+## Files
+
+### Helper Programs
+
+| File | Description |
+|------|-------------|
+| `cmd/inbox_view/main.go` | Renders a mock inbox populated with realistic email entries for screenshot capture. |
+| `cmd/email_view/main.go` | Renders a mock email view with headers, body content, and inline images for screenshot capture. |
+
+The rest are the tapes themselves
@@ -0,0 +1,13 @@
+# sender
+
+The `sender` package handles email composition and delivery over SMTP. It constructs properly formatted multipart MIME messages and sends them through the configured SMTP server.
+
+## Architecture
+
+This package is the SMTP client layer for Matcha. It:
+
+- Builds multipart MIME messages with plain text, HTML, inline images, and file attachments
+- Supports S/MIME detached signing and envelope encryption using PKCS#7
+- Handles SMTP authentication with both PLAIN and LOGIN mechanisms (fallback for servers like Mailo)
+- Supports both implicit TLS (port 465) and STARTTLS (other ports)
+- Generates unique Message-IDs and handles reply threading via `In-Reply-To` and `References` headers
@@ -0,0 +1,12 @@
+# theme
+
+The `theme` package defines the color palette system for Matcha's terminal UI. It provides built-in themes and supports user-created custom themes.
+
+## Architecture
+
+Each theme is a set of named colors (accent, danger, warning, link, etc.) used consistently across all UI components. The package:
+
+- Defines 6 built-in themes: Matcha, Rose, Lavender, Ocean, Peach, and Catppuccin Mocha
+- Supports custom themes loaded from `~/.config/matcha/themes/*.json`
+- Maintains a global `ActiveTheme` variable that all UI components reference
+- Uses Lip Gloss color values for terminal-compatible color rendering
@@ -0,0 +1,41 @@
+# tui
+
+The `tui` package contains all terminal user interface components built with the [Bubble Tea](https://github.com/charmbracelet/bubbletea) framework. Each file implements a self-contained view or component following the Bubble Tea Model-View-Update (MVU) pattern.
+
+## Architecture
+
+The TUI layer is the interactive frontend of Matcha. Each view implements the `tea.Model` interface (`Init`, `Update`, `View`) and communicates with other views through typed messages. The main application (`main.go`) orchestrates navigation between views by swapping the active model.
+
+### Views
+
+| File | Description |
+|------|-------------|
+| `inbox.go` | Email inbox list with multi-account tab support. Handles pagination, keyboard navigation, and renders email items with sender, subject, and date. Supports different mailbox types (inbox, sent, trash, archive) and both multi-account and single-account modes. |
+| `email_view.go` | Full email display in a scrollable viewport. Shows headers (from, to, subject, date), rendered body content, attachment list, and S/MIME verification status. Manages inline image rendering through out-of-band stdout writes. |
+| `composer.go` | Email composition form with fields for To, CC, BCC, Subject, and Body. Features contact autocomplete, file attachment picker, signature insertion, account selection dropdown, and draft auto-saving. Supports reply mode with pre-filled headers and quoted text. |
+| `drafts.go` | Draft email list view. Displays saved drafts with subject, recipient, and timestamp. Allows opening drafts in the composer or deleting them. |
+| `folder_inbox.go` | Folder navigation sidebar with an email list. Displays IMAP folders in a left panel and the selected folder's emails in the main area. Handles folder selection and email loading per folder. |
+| `trash_archive.go` | Combined trash and archive view with tab-based switching between the two. Shares the inbox component structure but targets trash/archive mailboxes. |
+| `login.go` | Account login form supporting Gmail, iCloud, and custom IMAP/SMTP providers. Collects credentials, server settings, and optionally S/MIME certificate paths. Validates input before submission. |
+| `settings.go` | Settings panel for managing accounts (add/remove), configuring mailing lists, editing signatures, toggling image display, managing tips visibility, and setting up S/MIME certificates. |
+| `mailing_list.go` | Editor for creating and modifying mailing list groups (name + comma-separated email addresses). |
+| `choice.go` | Main menu / start screen. Presents account selection, navigation to inbox, compose, drafts, sent, folders, trash/archive, and settings. |
+| `filepicker.go` | File browser for selecting email attachments. Navigates the filesystem with directory listing and file selection. |
+
+### Supporting Files
+
+| File | Description |
+|------|-------------|
+| `styles.go` | Global Lip Gloss style definitions used across all views (dialog boxes, help text, tips, headings, body text). Also defines the `Status` component for spinner-based loading messages. |
+| `theme.go` | `RebuildStyles` function that updates all package-level style variables when the active theme changes, ensuring consistent colors across the UI. |
+| `messages.go` | Shared message types for inter-component communication: `ViewEmailMsg`, `SendEmailMsg`, `Credentials`, `ChooseServiceMsg`, `EmailResultMsg`, `ClearStatusMsg`, and the `MailboxKind` enum. |
+| `signature.go` | Textarea-based editor for composing and saving email signatures. |
+
+### Test Files
+
+| File | Description |
+|------|-------------|
+| `inbox_test.go` | Tests for inbox rendering and behavior. |
+| `email_view_test.go` | Tests for email view rendering. |
+| `composer_test.go` | Tests for email composition logic. |
+| `trash_archive_test.go` | Tests for trash/archive view behavior. |
@@ -0,0 +1,16 @@
+# view
+
+The `view` package handles rendering email content for terminal display. It converts HTML email bodies into styled terminal text with support for inline images, hyperlinks, and quoted reply formatting.
+
+## Architecture
+
+This package bridges raw email content (HTML/Markdown) and terminal output. It:
+
+- Parses HTML email bodies using goquery and converts them to styled terminal text
+- Renders hyperlinks using OSC 8 escape sequences (with fallback for unsupported terminals)
+- Supports inline image rendering via multiple terminal graphics protocols:
+ - **Kitty Graphics Protocol** (Kitty, Ghostty, WezTerm, Wayst, Konsole)
+ - **iTerm2 Image Protocol** (iTerm2, Warp)
+- Detects quoted reply sections (`>` prefixed lines and `On DATE, EMAIL wrote:` patterns) and renders them in styled quote boxes
+- Manages image lifecycle: fetching remote images, resolving CID references, caching, uploading to terminal memory (Kitty IDs), and calculating terminal row placement
+- Converts Markdown to HTML via Goldmark before processing