Phase 2: Gmail IMAP fetch (IPv4), FR-2 source address, real mail in dashboard (AUD-67)

- internal/mailfetch: stdlib-only read-only IMAP client (LOGIN, SELECT,
  UID SEARCH, UID FETCH) that always dials tcp4; IPv6 to Gmail is broken
  from .13 and caused a socket EOF.
- MIME parsing to text, RFC2047 header decoding, FR-2 source address:
  X-Pm-Original-To -> To -> Received 'for <addr>' -> Return-Path, never
  Delivered-To. The matched header is recorded for audit.
- store: Message upsert/list/count + LogAction; schema migration v2 adds
  imap_uid and imap_uidvalidity.
- server: dashboard and /partials/inbox render real mail grouped by
  category with a recommended action; POST /actions/fetch runs a scan
  (CSRF-checked); nav counts; 'Check mail' button.
- config: GMAIL_USER, GMAIL_APP_PASSWORD, IMAP host/port/lookback/max.
- cmd: -fetch runs one scan and exits (n8n/CLI entry point, FR-1).
- compose/.env.example expose the Gmail + IMAP settings.
- tests: FR-2 precedence, MIME bodies, IMAP literal/parser, store
  upsert/migration, inbox rendering.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

cmd/email-agent/main.go

@@ -13,6 +13,7 @@ import (
 	"time"
 
 	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/config"
+	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/mailfetch"
 	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/server"
 	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/store"
 	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/version"
@@ -22,6 +23,7 @@ func main() {
 	var (
 		showVersion = flag.Bool("version", false, "print version information and exit")
 		healthcheck = flag.Bool("healthcheck", false, "probe the local /health endpoint and exit")
+		fetchNow    = flag.Bool("fetch", false, "run one Gmail IMAP scan and exit")
 	)
 	flag.Parse()
 
@@ -47,6 +49,14 @@ func main() {
 		return
 	}
 
+	if *fetchNow {
+		if err := runFetch(cfg, logger); err != nil {
+			fmt.Fprintf(os.Stderr, "fetch failed: %v\n", err)
+			os.Exit(1)
+		}
+		return
+	}
+
 	if err := run(cfg, logger); err != nil {
 		logger.Error("fatal", "error", err)
 		os.Exit(1)
@@ -91,6 +101,30 @@ func run(cfg *config.Config, logger *slog.Logger) error {
 	return srv.Run(ctx)
 }
 
+// runFetch performs a single IMAP scan and exits. It is the entry point n8n
+// (FR-1) and manual operations use to trigger a sync without the HTTP UI.
+func runFetch(cfg *config.Config, logger *slog.Logger) error {
+	if !cfg.GmailConfigured() {
+		return mailfetch.ErrNoCredentials
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	st, err := store.Open(ctx, cfg.DBPath)
+	if err != nil {
+		return fmt.Errorf("open store: %w", err)
+	}
+	defer func() { _ = st.Close() }()
+
+	sum, err := mailfetch.NewFetcher(cfg, st, logger).Fetch(ctx)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("fetched=%d stored=%d uidvalidity=%d since=%s\n",
+		sum.Fetched, sum.Stored, sum.UIDValidity, sum.Since.Format("2006-01-02"))
+	return nil
+}
+
 // probeHealth requests the local health endpoint. It exists so the container
 // healthcheck does not need an external HTTP client in the image.
 func probeHealth(port int) error {