chore(vnc): bootstrap VNCmail+ fork — vnc/ layer + Vercel runbook

Fork of bulwarkmail/webmail for deploy on Vercel as project vncmail-plus.
Adds vnc/ customization layer (branding, overrides, VNC-CHANGES log),
Vercel env template, and VNCMAIL-SETUP.md runbook. No upstream files touched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

VNCMAIL-SETUP.md

@@ -0,0 +1,66 @@
+# VNCmail+ — Vercel setup runbook
+
+VNCmail+ is VNC's fork of [Bulwark](https://github.com/bulwarkmail/webmail), a
+Next.js (App Router) JMAP webmail client for **Stalwart**. Stalwart is the source
+of truth; VNCmail+ is the UI. This repo deploys to **Vercel** as project
+`vncmail-plus`.
+
+> **License:** AGPL-3.0. Serving a modified VNCmail+ to users over the network
+> obligates VNC to offer those users the corresponding source. Keeping this fork
+> public (with a "Source" link in the imprint/UI) satisfies that. Loop in legal
+> before a public/customer-facing launch if a closed fork is ever desired.
+
+## Architecture (why Vercel works here)
+
+- JMAP calls go through **server-side Next.js `/api/*` routes** (see `proxy.ts`),
+  i.e. Vercel Functions talk to Stalwart server-to-server → **no browser CORS**.
+- Config is **runtime-read**, so env changes don't need a rebuild.
+- Real data (mail/calendar/contacts) lives in **Stalwart**, so Vercel's
+  ephemeral filesystem is fine. The only features that want a persistent disk
+  (settings-sync, admin-dashboard persistence, telemetry) are **off by default**
+  and left off here. If VNC ever needs those persisted, host the upstream Docker
+  image on VNC infra instead of / alongside Vercel.
+
+## Branches (dev-first)
+
+| Branch | Role |
+|--------|------|
+| `main` | Tracks upstream Bulwark releases; kept as clean as possible |
+| `dev`  | VNC integration + **Vercel production branch (for now)** |
+| `vnc/*`| Feature branches for UI work |
+
+All VNC customization lives under `vnc/` (see `vnc/VNC-CHANGES.md`).
+
+## One-time Vercel setup
+
+1. **New Project** → import `brvncde-dotcom/vncmail-plus`.
+2. Project name: **`vncmail-plus`** (display "VNCmail+"). Framework: Next.js (auto).
+3. **Settings → Git → Production Branch = `dev`** (move to `main` only when you
+   cut a real prod domain).
+4. **Settings → Environment Variables:** paste from `vnc/vercel.env.template`.
+   - Generate the secret: `openssl rand -base64 32`
+   - Mark `SESSION_SECRET` as **Sensitive**.
+5. **Deploy.** Then open the deployment URL and log in as a
+   `@sandbox.vnc.de` test user (anyone in `vncdirectory.sandbox.vnc.de`).
+
+## Custom domain (recommended)
+
+Add a subdomain of the Stalwart parent, e.g. `mail.sandbox.vnc.de` or
+`vncmailplus.sandbox.vnc.de`, in Vercel → Domains. Same parent domain keeps
+everything tidy and avoids any future cross-origin edge cases.
+
+## Syncing upstream later
+
+```bash
+git fetch upstream
+git checkout main && git merge upstream/main   # bring in new Bulwark release
+git checkout dev  && git merge main            # integrate; resolve via vnc/VNC-CHANGES.md
+git push origin main dev                        # Vercel redeploys dev
+```
+
+## Auth
+
+Basic auth via Stalwart is the default — users sign in with their
+`@sandbox.vnc.de` address + password; VNCmail+ authenticates them over JMAP. No
+extra config. (SSO via vncdirectory/OIDC is a later option — see
+`vnc/vercel.env.template`.)

vnc/VNC-CHANGES.md

@@ -0,0 +1,26 @@
+# VNC-CHANGES — VNCmail+ divergence log
+
+VNCmail+ is a fork of [bulwarkmail/webmail](https://github.com/bulwarkmail/webmail)
+(AGPL-3.0). This file records **every** intentional divergence from upstream so
+that merging new upstream releases stays a triage exercise, not an archaeology dig.
+
+## Rules of the fork
+
+1. **Keep upstream files unmodified whenever possible.** Prefer env vars
+   (branding), the `vnc/overrides/` layer, and additive files over editing files
+   inside `app/`, `components/`, `lib/`, `stores/`.
+2. **Every edit to an upstream file gets a one-line entry below** — path, what,
+   why. No silent edits.
+3. **Branches:** `main` tracks upstream releases (kept clean); `dev` is the VNC
+   integration + Vercel deploy branch; `vnc/*` are feature branches.
+4. **Syncing upstream:** `git fetch upstream && git merge upstream/main` onto
+   `main`, then merge `main` into `dev`. Resolve using this log.
+
+## Divergences
+
+| Date | File / area | Change | Why |
+|------|-------------|--------|-----|
+| 2026-08-03 | `vnc/` (new) | Added VNC customization dir + this log | Fork bootstrap |
+| 2026-08-03 | `VNCMAIL-SETUP.md` (new) | Vercel deploy runbook | Deploy on Vercel as project "VNCmail+" |
+
+_(append new rows as you diverge)_

vnc/branding/README.md

@@ -0,0 +1,19 @@
+# vnc/branding
+
+Drop VNCmail+ brand assets here (logos, favicon, PWA icons), then point the
+runtime branding env vars at them. Most branding needs **no code edit** — it's
+all env-driven and read at runtime.
+
+Suggested assets:
+- `logo-light.svg` / `logo-dark.svg`  → `APP_LOGO_LIGHT_URL` / `APP_LOGO_DARK_URL`
+- `login-logo-light.svg` / `login-logo-dark.svg` → `LOGIN_LOGO_LIGHT_URL` / `LOGIN_LOGO_DARK_URL`
+- `favicon.ico` → `FAVICON_URL`
+- `pwa-icon.png` (512×512) → `PWA_ICON_URL`
+
+To serve these from the app itself, copy them into `public/branding/` and set the
+URLs to `/branding/<file>`. To serve from a CDN, set absolute URLs.
+
+Theme colors: `PWA_THEME_COLOR`, `PWA_BACKGROUND_COLOR`.
+
+See `VNCMAIL-SETUP.md` and upstream `.env.example` (branding section) for the full
+list.

vnc/overrides/README.md

@@ -0,0 +1,15 @@
+# vnc/overrides
+
+Home for VNC-specific UI overrides that go beyond env-driven branding.
+
+Keep changes here (and imported into upstream files with a **single, logged**
+edit) rather than editing upstream components in place — it keeps
+`git merge upstream/main` cheap.
+
+Pattern:
+- Put a replacement component / theme token / CSS layer in this folder.
+- Wire it in with the smallest possible edit to the upstream file.
+- Record that edit in `../VNC-CHANGES.md`.
+
+If you find yourself editing many upstream files for one feature, stop and
+reconsider whether it can be an override or an upstream contribution instead.

vnc/vercel.env.template

@@ -0,0 +1,38 @@
+# ────────────────────────────────────────────────────────────────
+# VNCmail+ · Vercel environment variables
+# Paste these into Vercel → Project "vncmail-plus" → Settings →
+# Environment Variables. Do NOT commit real secret values.
+# All vars are read at RUNTIME (no rebuild needed to change them),
+# except NEXT_PUBLIC_BASE_PATH.
+# ────────────────────────────────────────────────────────────────
+
+# --- Core: connect to Stalwart over JMAP ---
+# Setting this skips the setup wizard and uses env-managed config
+# (important on Vercel, where the wizard's disk config is not persisted).
+JMAP_SERVER_URL=https://stalwart.sandbox.vnc.de
+
+# --- Session encryption (mark as "Sensitive" in Vercel) ---
+# Generate with:  openssl rand -base64 32
+SESSION_SECRET=__PASTE_GENERATED_SECRET__
+
+# --- Branding ---
+APP_NAME=VNCmail+
+APP_SHORT_NAME=VNCmail+
+LOGIN_COMPANY_NAME=VNC
+
+# --- Quiet the periodic update check (avoids disk/network on serverless) ---
+BULWARK_UPDATE_CHECK=off
+
+# ────────────────────────────────────────────────────────────────
+# Intentionally NOT set (defaults are correct for a Vercel deploy):
+#   OAUTH_ENABLED           → unset = basic auth via Stalwart (chosen)
+#   SETTINGS_SYNC_ENABLED   → unset = off (needs a persistent disk; skip on Vercel)
+#   BULWARK_TELEMETRY       → unset = off (opt-in only)
+#   NEXT_PUBLIC_BASE_PATH   → unset = deploy at domain root
+#
+# Add later if needed:
+#   OAUTH_ENABLED / OAUTH_ISSUER_URL / OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET
+#     → SSO via vncdirectory (follow-up, not first deploy)
+#   APP_LOGO_LIGHT_URL / LOGIN_LOGO_LIGHT_URL / FAVICON_URL / PWA_ICON_URL
+#     → VNC brand assets (see vnc/branding/)
+# ────────────────────────────────────────────────────────────────