docs: update contributing guidelines and enhance README formatting

CONTRIBUTING.md

@@ -7,17 +7,20 @@ Thank you for your interest in contributing to Bulwark Webmail! This document pr
 ### Development Setup
 
 1. **Fork and clone** the repository:
+
    ```bash
    git clone https://github.com/bulwarkmail/webmail.git
    cd webmail
    ```
 
 2. **Install dependencies**:
+
    ```bash
    npm install
    ```
 
 3. **Set up environment**:
+
    ```bash
    cp .env.example .env.local
    # Edit .env.local with your JMAP server URL
@@ -75,9 +78,10 @@ This project uses **next-intl** for internationalization. Please follow these gu
 ### Key Rules
 
 1. **Never hardcode user-facing text** - Always use translations:
+
    ```tsx
-   const t = useTranslations('namespace');
+   const t = useTranslations("namespace");
-   return <div>{t('key')}</div>;
+   return <div>{t("key")}</div>;
    ```
 
 2. **Translation file locations**:
@@ -109,6 +113,7 @@ This project uses **next-intl** for internationalization. Please follow these gu
 ### Before Submitting
 
 1. **Create a feature branch**:
+
    ```bash
    git checkout -b feature/your-feature-name
    ```
@@ -147,6 +152,7 @@ Follow the conventional commits format:
 - `chore:` - Maintenance tasks
 
 Examples:
+
 ```
 feat: add email threading support
 fix: resolve attachment download issue
@@ -184,6 +190,7 @@ webmail/
 ## Questions?
 
 If you have questions about contributing, feel free to:
+
 - Open an issue for discussion
 - Check existing issues and pull requests
 

README.md

@@ -200,6 +200,7 @@ OAUTH_ISSUER_URL=                 # optional, for external IdPs (Keycloak, Authe
 ```
 
 Endpoints are auto-discovered via `.well-known/oauth-authorization-server` or `.well-known/openid-configuration`.
+
 </details>
 
 <details>
@@ -210,12 +211,13 @@ SESSION_SECRET=your-secret-key    # Generate with: openssl rand -base64 32
 ```
 
 Credentials encrypted with AES-256-GCM, stored in an httpOnly cookie (30-day expiry).
+
 </details>
 
 ## Keyboard Shortcuts
 
 | Key           | Action                  |
-|-----|--------|
+| ------------- | ----------------------- |
 | `j` / `k`     | Navigate between emails |
 | `Enter` / `o` | Open email              |
 | `Esc`         | Close / deselect        |
@@ -231,7 +233,7 @@ Credentials encrypted with AES-256-GCM, stored in an httpOnly cookie (30-day exp
 ## Tech Stack
 
 |               |                                                   |
-|---|---|
+| ------------- | ------------------------------------------------- |
 | **Framework** | [Next.js 16](https://nextjs.org/) with App Router |
 | **Language**  | TypeScript                                        |
 | **Styling**   | [Tailwind CSS v4](https://tailwindcss.com/)       |

ROADMAP.md

@@ -5,12 +5,14 @@ This document tracks the development status and planned features for Bulwark Web
 ## Completed Features
 
 ### Core Infrastructure
+
 - [x] Next.js 16 with TypeScript and App Router
 - [x] Tailwind CSS v4 with Oxide engine
 - [x] Zustand state management
 - [x] Custom JMAP client implementation (RFC 8620)
 
 ### Authentication
+
 - [x] Login with JMAP server authentication
 - [x] Session management (no password storage for security)
 - [x] Username autocomplete with history
@@ -23,6 +25,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] "Remember me" session persistence for Basic Auth (AES-256-GCM encrypted httpOnly cookie)
 
 ### JMAP Server Connection
+
 - [x] Session establishment and keep-alive
 - [x] Connection error handling and retries
 - [x] CORS error detection with actionable user guidance
@@ -32,6 +35,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Shared folders support (multi-account access)
 
 ### Email Operations
+
 - [x] Email fetching and display
 - [x] Full HTML email rendering
 - [x] Compose, reply, reply-all, forward
@@ -48,6 +52,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Email threading (Gmail-style inline expansion)
 
 ### Real-time Updates
+
 - [x] EventSource for JMAP push notifications
 - [x] State synchronization
 - [x] Email arrival notifications
@@ -55,6 +60,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Mailbox change handling
 
 ### User Interface
+
 - [x] Three-pane layout (sidebar, list, viewer)
 - [x] Minimalist design system
 - [x] Dark and light theme support
@@ -86,6 +92,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Screen reader live region announcements (sr-only)
 
 ### Internationalization
+
 - [x] English language support
 - [x] French language support
 - [x] Japanese language support
@@ -98,6 +105,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Language preference persistence
 
 ### Security & Accessibility
+
 - [x] External content blocked by default
 - [x] HTML sanitization with DOMPurify
 - [x] User control for loading external content
@@ -114,6 +122,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Screen reader sr-only live region for dynamic announcements
 
 ### Identity Management
+
 - [x] Multiple sender identities (name, email, signature)
 - [x] Sub-addressing support (user+tag@domain.com)
 - [x] Per-identity signatures
@@ -123,6 +132,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Primary identity (matching login) selected by default in composer
 
 ### Address Book & Contacts
+
 - [x] Contact store with JMAP sync and local fallback
 - [x] Contact CRUD operations (create, read, update, delete)
 - [x] Contacts list view with search/filter
@@ -136,12 +146,14 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] i18n support for contacts (all 8 languages)
 
 ### Vacation Responder
+
 - [x] JMAP VacationResponse singleton management
 - [x] Settings tab with date range and message configuration
 - [x] Sidebar indicator when vacation auto-reply is active
 - [x] i18n support (all 8 languages)
 
 ### Calendar Integration
+
 - [x] JMAP Calendar types (RFC 8984) and client methods
 - [x] Calendar capability detection (urn:ietf:params:jmap:calendars)
 - [x] Calendar store with Zustand (persist middleware)
@@ -177,6 +189,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Event duplication button in modal (clones event +1 day, opens for editing)
 
 ### Email Filters
+
 - [x] JMAP Sieve Scripts (RFC 9661) with capability detection
 - [x] Visual rule builder (conditions: From/To/Cc/Subject/Header/Size/Body, actions: Move/Copy/Forward/Mark read/Star/Label/Discard/Reject/Keep/Stop)
 - [x] Raw Sieve script editor with syntax validation
@@ -189,6 +202,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] i18n support (all 8 languages)
 
 ### Email Templates
+
 - [x] Reusable email templates with local storage persistence
 - [x] Category organization (General, Business, Personal, Support, Follow-up, custom)
 - [x] Dynamic placeholder variables with auto-fill from composer context
@@ -200,10 +214,12 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] i18n support (all 8 languages)
 
 ### Email Display
+
 - [x] Proper email layout without horizontal scroll or clipping
 - [x] Blocked image container collapsing (no empty spaces in newsletters)
 
 ### Testing
+
 - [x] Unit tests for validation utilities (57 tests)
 - [x] Unit tests for email sanitization (27 tests)
 - [x] Unit tests for color transformation (40 tests)
@@ -226,6 +242,7 @@ This document tracks the development status and planned features for Bulwark Web
 - [x] Playwright E2E framework setup
 
 ### Deployment
+
 - [x] Runtime environment variables (Docker-friendly configuration)
 - [x] Health check endpoint
 - [x] Docker support (multi-stage build, docker-compose, standalone output)
@@ -238,26 +255,31 @@ This document tracks the development status and planned features for Bulwark Web
 ## Planned Features
 
 ### Advanced Features
+
 - [ ] Free/busy queries (Principal/getAvailability)
 - [ ] Calendar sharing UI (JMAP Sharing RFC 9670)
 - [ ] Email encryption (PGP/GPG)
 
 ### Performance Optimizations
+
 - [ ] Email content caching
 - [ ] Bundle size optimization
 - [ ] Service worker for offline support
 - [ ] Lazy loading for attachments
 
 ### Testing (Remaining)
+
 - [ ] E2E tests with real JMAP server
 - [ ] Accessibility testing
 - [ ] Performance testing
 
 ### Deployment
+
 - [ ] Production build optimizations
 - [ ] Monitoring and logging
 
 ### Security Enhancements
+
 - [ ] Rate limiting
 
 ## Known Issues

docker-compose.yml

@@ -6,7 +6,15 @@ services:
     env_file:
       - .env.local
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/api/health"]
+      test:
+        [
+          "CMD",
+          "wget",
+          "--no-verbose",
+          "--tries=1",
+          "--spider",
+          "http://127.0.0.1:3000/api/health",
+        ]
       interval: 30s
       timeout: 5s
       retries: 3

specifications/addon-plugin-theme-concept.md

@@ -37,7 +37,7 @@ This document describes a system that allows the Bulwark Webmail application to
 ### Rebuild Requirements
 
 | Addon Type | Source                       | Rebuild Needed?                             |
-|-----------|--------|----------------|
+| ---------- | ---------------------------- | ------------------------------------------- |
 | Theme      | Bundled (`/addons/themes/`)  | **Yes** — included at build time            |
 | Theme      | URL (remote)                 | **No** — CSS loaded via `<link>` at runtime |
 | Plugin     | Bundled (`/addons/plugins/`) | **Yes** — included at build time            |
@@ -57,7 +57,7 @@ Bundled addons are compiled into the app's static assets during `next build`. Ad
 ## 2. Terminology
 
 | Term           | Definition                                                                                                                                 |
-|------|-----------|
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Addon**      | Any installable extension — umbrella term for themes and plugins.                                                                          |
 | **Theme**      | An addon that only customizes visual appearance (colors, fonts, spacing, density). Ships as CSS + a manifest. Contains no executable code. |
 | **Plugin**     | An addon that adds or modifies functionality. Ships as a JS/TS module + a manifest. May include a theme.                                   |
@@ -80,14 +80,14 @@ Every addon has an `addon.json` at its root:
   "description": "A brief description.",
   "author": {
     "name": "Jane Doe",
-    "url": "https://example.com"
+    "url": "https://example.com",
   },
   "license": "MIT",
   "homepage": "https://example.com/my-addon",
 
   // ── Compatibility ──
   "engine": {
-    "webmail": ">=1.0.0"                 // Required host app version range
+    "webmail": ">=1.0.0", // Required host app version range
   },
 
   // ── Type ──
@@ -101,7 +101,7 @@ Every addon has an `addon.json` at its root:
   "theme": {
     "variables": "theme.css", // CSS file with variable overrides
     "presets": ["light", "dark"], // Which base modes it provides
-    "preview": "preview.png"            // Screenshot for settings UI
+    "preview": "preview.png", // Screenshot for settings UI
   },
 
   // ── Permissions (plugins only) ──
@@ -119,20 +119,14 @@ Every addon has an `addon.json` at its root:
     "navigation:tab", // Add a top-level navigation tab
     "context-menu:email", // Extend email context menu
     "keyboard-shortcuts", // Register keyboard shortcuts
-    "external-fetch"                    // Fetch external URLs (declared origins)
+    "external-fetch", // Fetch external URLs (declared origins)
   ],
 
   // ── External Origins (if external-fetch permission is declared) ──
-  "allowedOrigins": [
+  "allowedOrigins": ["https://api.example.com"],
-    "https://api.example.com"
-  ],
 
   // ── Slots (declares which UI slots the plugin uses) ──
-  "slots": [
+  "slots": ["sidebar.bottom", "compose.toolbar", "viewer.actions"],
-    "sidebar.bottom",
-    "compose.toolbar",
-    "viewer.actions"
-  ],
 
   // ── Settings Schema (plugin-specific preferences) ──
   "settings": {
@@ -140,17 +134,17 @@ Every addon has an `addon.json` at its root:
       "type": "string",
       "label": "API Key",
       "description": "Your API key for the service.",
-      "secret": true
+      "secret": true,
     },
     "enabled": {
       "type": "boolean",
       "label": "Enable integration",
-      "default": true
+      "default": true,
-    }
+    },
   },
 
   // ── i18n ──
-  "locales": "locales/"                  // Directory with {locale}.json files
+  "locales": "locales/", // Directory with {locale}.json files
 }
 ```
 
@@ -210,7 +204,7 @@ User selects theme in Settings → Appearance
 ### 4.3 Theme Capabilities
 
 | Capability        | Mechanism                                          |
-|-----------|-----------|
+| ----------------- | -------------------------------------------------- |
 | Colors            | Override `--color-*` CSS variables                 |
 | Typography        | Override `--font-family-*` variables               |
 | Spacing/density   | Override `--spacing-density` multiplier            |
@@ -271,7 +265,9 @@ export function activate(ctx: PluginContext) {
   ctx.contextMenu.register("email", {
     label: ctx.i18n.t("translateEmail"),
     icon: "Languages",
-    action: (emailId) => { /* ... */ },
+    action: (emailId) => {
+      /* ... */
+    },
   });
 }
 
@@ -411,7 +407,8 @@ Next.js `import()` only resolves modules known at build time. To load plugins fr
 async function loadRemotePlugin(url: string): Promise<PluginModule> {
   // 1. Fetch the plugin's JS bundle as text
   const response = await fetch(url);
-  if (!response.ok) throw new Error(`Failed to fetch plugin: ${response.status}`);
+  if (!response.ok)
+    throw new Error(`Failed to fetch plugin: ${response.status}`);
   const code = await response.text();
 
   // 2. Validate size limit (500 KB default)
@@ -437,11 +434,11 @@ async function loadRemotePlugin(url: string): Promise<PluginModule> {
 
 // Shared dependencies exposed to plugins — avoids bundling duplicates
 const SHARED_DEPS: Record<string, unknown> = {
-  "react": React,
+  react: React,
   "react/jsx-runtime": jsxRuntime,
   "lucide-react": lucideIcons,
   "date-fns": dateFns,
-  "sonner": sonner,
+  sonner: sonner,
 };
 ```
 
@@ -531,7 +528,7 @@ function Slot({ name }: { name: string }) {
 #### Available Slots
 
 | Slot Name           | Location                               | Use Case                              |
-|-----------|----------|----------|
+| ------------------- | -------------------------------------- | ------------------------------------- |
 | `sidebar.top`       | Top of sidebar, below compose button   | Quick-access widgets                  |
 | `sidebar.bottom`    | Bottom of sidebar, above storage quota | Extra navigation, widgets             |
 | `navigation.tabs`   | Navigation rail, below contacts icon   | New top-level views                   |
@@ -552,7 +549,7 @@ Plugins can listen to app events and state transitions:
 #### Email Hooks
 
 | Event                       | Payload                 | Description                       |
-|-------|---------|-------------|
+| --------------------------- | ----------------------- | --------------------------------- |
 | `email:selected`            | `{ emailId, email }`    | User selected an email            |
 | `email:opened`              | `{ emailId, email }`    | Email viewer rendered             |
 | `email:compose:open`        | `{ mode, replyTo? }`    | Composer opened                   |
@@ -565,7 +562,7 @@ Plugins can listen to app events and state transitions:
 #### Calendar Hooks
 
 | Event                    | Payload              | Description            |
-|-------|---------|-------------|
+| ------------------------ | -------------------- | ---------------------- |
 | `calendar:event:created` | `{ event }`          | New event created      |
 | `calendar:event:updated` | `{ event, changes }` | Event modified         |
 | `calendar:event:deleted` | `{ eventId }`        | Event deleted          |
@@ -574,7 +571,7 @@ Plugins can listen to app events and state transitions:
 #### Contact Hooks
 
 | Event              | Payload         | Description         |
-|-------|---------|-------------|
+| ------------------ | --------------- | ------------------- |
 | `contact:selected` | `{ contactId }` | Contact selected    |
 | `contact:created`  | `{ contact }`   | New contact created |
 | `contact:updated`  | `{ contact }`   | Contact modified    |
@@ -582,7 +579,7 @@ Plugins can listen to app events and state transitions:
 #### App Hooks
 
 | Event                | Payload        | Description                  |
-|-------|---------|-------------|
+| -------------------- | -------------- | ---------------------------- |
 | `app:ready`          | `{}`           | App fully loaded             |
 | `app:theme:changed`  | `{ theme }`    | Theme switched               |
 | `app:locale:changed` | `{ locale }`   | Language changed             |
@@ -610,7 +607,7 @@ Permissions are enforced at the `PluginContext` level — if a plugin didn't dec
 ### 8.2 Sandboxing Strategy
 
 | Layer               | Mechanism                                                                                                                                                                                        |
-|-------|-----------|
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Store access**    | `PluginContext` exposes only permitted store slices. Write access returns proxied objects — mutations are validated before applying.                                                             |
 | **DOM access**      | Plugin components render inside an `<AddonErrorBoundary>`. They receive a scoped React tree — no direct `document` manipulation.                                                                 |
 | **Network**         | `ctx.fetch()` is a controlled wrapper. Requests are only allowed to origins listed in `allowedOrigins`. All other `fetch` / `XMLHttpRequest` calls from plugin code are blocked via CSP headers. |
@@ -621,6 +618,7 @@ Permissions are enforced at the `PluginContext` level — if a plugin didn't dec
 ### 8.3 Content Security Policy
 
 Theme CSS is sanitized to disallow:
+
 - `url()` references to external domains (only data URIs and same-origin).
 - `@import` statements.
 - `expression()` or `behavior:` (legacy IE attack vectors).
@@ -651,7 +649,7 @@ function AddonErrorBoundary({ addonId, children }) {
 ### 9.1 Addon Formats
 
 | Format         | Description                                   | Use Case                            |
-|--------|-------------|----------|
+| -------------- | --------------------------------------------- | ----------------------------------- |
 | **Bundled**    | Shipped inside the app's `/addons/` directory | Default themes, first-party plugins |
 | **URL**        | Loaded from a remote URL at runtime           | Self-hosted or third-party addons   |
 | **Local file** | Loaded from a local path (dev mode only)      | Plugin development                  |
@@ -692,12 +690,14 @@ addons/
 ### 9.4 Installation Flow
 
 **From URL:**
+
 1. User pastes addon URL into Settings → Addons → "Install from URL".
 2. App fetches `{url}/addon.json`, validates schema and compatibility.
 3. Manifest is stored in addon registry (`localStorage`).
 4. On next activation, the addon's assets are fetched and cached.
 
 **Bundled:**
+
 1. Addons in `/addons/` are auto-discovered at build time.
 2. A generated `addon-registry.json` maps addon IDs to their local paths.
 3. Bundled addons appear pre-installed (but can be disabled).
@@ -779,6 +779,7 @@ Appearance
 ```
 
 When a theme is selected, the app:
+
 1. Sets `data-theme` attribute on `<html>`.
 2. Loads the theme's CSS file.
 3. Persists the choice in `ThemeStore`.
@@ -894,6 +895,7 @@ nord-theme/
 ```
 
 `addon.json`:
+
 ```json
 {
   "id": "org.nordtheme.bulwark-webmail",
@@ -925,6 +927,7 @@ email-translator/
 ```
 
 `addon.json`:
+
 ```json
 {
   "id": "com.example.email-translator",