feat(timeutil): support configurable timezone for timestamp display (#346)

* feat(timeutil): support configurable timezone for timestamp display

Add ENGRAM_TIMEZONE env var to control how timestamps are displayed
across all output surfaces (mem_context, mem_search, mem_timeline,
TUI, and CLI commands). Storage stays in UTC; only display is converted.

- New internal/timeutil package with FormatLocal() helper
- Respects ENGRAM_TIMEZONE (e.g. America/Bogota); falls back to system local
- Applied to: tui/view.go, mcp.go, store.FormatContext, cmd/engram search+timeline

Closes #169

* feat(dashboard): honor ENGRAM_TIMEZONE in cards and accept SQLite timestamps

Two reports landed on #169 after #346 was opened: pepe-alehop confirmed
the binary-level env approach is needed in Docker, and quirozino traced
a separate bug in the dashboard helper where formatTimestamp parsed
only RFC3339 and silently returned raw UTC for SQLite-style values
("YYYY-MM-DD HH:MM:SS"), leaking UTC into the UI for any value
arriving in that shape.

Extends the existing timeutil package with FormatLocalWithLayout so UI
surfaces can pass their own layout while keeping ENGRAM_TIMEZONE
conversion centralized. The dashboard helper now delegates to it and
accepts both RFC3339 and SQLite-style inputs.

FormatLocal becomes a thin wrapper over FormatLocalWithLayout with the
default layout, so no caller changes outside the dashboard.

Adds regression tests:
- dashboard formatTimestamp resolves the SQLite-style #169 report
- formatTimestamp honors ENGRAM_TIMEZONE (Bogota + Madrid cases)
- empty / unparseable inputs preserve the documented contract
- timeutil FormatLocalWithLayout round-trips the friendly dashboard layout

---------

Co-authored-by: Alan Buscaglia <gentlemanprogramming@gmail.com>

Author: carlosmoradev

cmd/engram/main.go

@@ -39,6 +39,7 @@ import (
 	"github.com/Gentleman-Programming/engram/internal/setup"
 	"github.com/Gentleman-Programming/engram/internal/store"
 	engramsync "github.com/Gentleman-Programming/engram/internal/sync"
+	"github.com/Gentleman-Programming/engram/internal/timeutil"
 	"github.com/Gentleman-Programming/engram/internal/tui"
 	versioncheck "github.com/Gentleman-Programming/engram/internal/version"
 
@@ -975,7 +976,7 @@ func cmdSearch(cfg store.Config) {
 		fmt.Printf("[%d] #%d (%s) — %s\n    %s\n    %s%s | scope: %s\n\n",
 			i+1, r.ID, r.Type, r.Title,
 			truncate(r.Content, 300),
-			r.CreatedAt, project, r.Scope)
+			timeutil.FormatLocal(r.CreatedAt), project, r.Scope)
 	}
 }
 
@@ -1115,7 +1116,7 @@ func cmdTimeline(cfg store.Config) {
 	// Focus
 	fmt.Printf(">>> #%d [%s] %s <<<\n", result.Focus.ID, result.Focus.Type, result.Focus.Title)
 	fmt.Printf("    %s\n", truncate(result.Focus.Content, 500))
-	fmt.Printf("    %s\n\n", result.Focus.CreatedAt)
+	fmt.Printf("    %s\n\n", timeutil.FormatLocal(result.Focus.CreatedAt))
 
 	// After
 	if len(result.After) > 0 {

internal/cloud/dashboard/helpers.go

@@ -13,6 +13,7 @@ import (
 	"unicode/utf8"
 
 	"github.com/Gentleman-Programming/engram/internal/cloud/cloudstore"
+	"github.com/Gentleman-Programming/engram/internal/timeutil"
 )
 
 // ─── Pagination ─────────────────────────────────────────────────────────────
@@ -238,19 +239,27 @@ func typePillClass(activeType, candidate string) string {
 	return "type-pill"
 }
 
+// dashboardTimestampLayout is the human-friendly layout shown on dashboard cards
+// (e.g. "22 May 2026 11:31"). Storage stays UTC; only the rendered string changes.
+const dashboardTimestampLayout = "02 Jan 2006 15:04"
+
+// formatTimestamp renders a stored UTC timestamp for dashboard display. It accepts
+// both RFC3339 and SQLite-style values ("YYYY-MM-DD HH:MM:SS") and honors
+// ENGRAM_TIMEZONE for the display zone, falling back to system local time.
+//
+// Returns "-" for an empty string. If the value cannot be parsed in any supported
+// layout, the original string is returned unchanged so we never lose data on
+// malformed timestamps.
 func formatTimestamp(ts string) string {
 	ts = strings.TrimSpace(ts)
 	if ts == "" {
 		return "-"
 	}
-	parsed, err := time.Parse(time.RFC3339Nano, ts)
-	if err != nil {
-		return ts
-	}
-	return parsed.Local().Format("02 Jan 2006 15:04")
+	return timeutil.FormatLocalWithLayout(ts, dashboardTimestampLayout)
 }
 
 // ADAPTED: legacy had formatTimestampPtr(*string); integrated uses string fields.
+// Cards that show "last seen" or similar nullable values render "Never" instead of "-".
 func formatTimestampStr(ts string) string {
 	if ts == "" {
 		return "Never"

internal/cloud/dashboard/helpers_test.go

@@ -1,6 +1,7 @@
 package dashboard
 
 import (
+	"os"
 	"strings"
 	"testing"
 )
@@ -78,3 +79,79 @@ func TestSanitizeDashboardNextNormalizesAndConstrainsPath(t *testing.T) {
 		})
 	}
 }
+
+// withEngramTimezone forces ENGRAM_TIMEZONE for the test body and restores
+// the original value afterwards, so timezone-sensitive tests stay isolated.
+func withEngramTimezone(t *testing.T, tz string) {
+	t.Helper()
+	old, hadOld := os.LookupEnv("ENGRAM_TIMEZONE")
+	t.Setenv("ENGRAM_TIMEZONE", tz)
+	t.Cleanup(func() {
+		if hadOld {
+			os.Setenv("ENGRAM_TIMEZONE", old)
+			return
+		}
+		os.Unsetenv("ENGRAM_TIMEZONE")
+	})
+}
+
+// TestFormatTimestampParsesSQLiteStyleInput is the regression test for the bug
+// reported on #169 by @quirozino. The legacy dashboard helper called
+// time.Parse(time.RFC3339Nano, ts) which silently failed on SQLite-style
+// "YYYY-MM-DD HH:MM:SS" values and leaked raw UTC strings into the UI. The new
+// helper delegates to timeutil and must convert these values correctly.
+func TestFormatTimestampParsesSQLiteStyleInput(t *testing.T) {
+	withEngramTimezone(t, "America/Bogota") // UTC-5
+
+	// SQLite-style timestamp stored as UTC noon → 07:00 in Bogota.
+	got := formatTimestamp("2026-05-22 12:00:00")
+	want := "22 May 2026 07:00"
+	if got != want {
+		t.Fatalf("formatTimestamp(SQLite-style) = %q, want %q (regression of #169 dashboard bug)", got, want)
+	}
+}
+
+func TestFormatTimestampParsesRFC3339Input(t *testing.T) {
+	withEngramTimezone(t, "America/Bogota")
+
+	got := formatTimestamp("2026-05-22T12:00:00Z")
+	want := "22 May 2026 07:00"
+	if got != want {
+		t.Fatalf("formatTimestamp(RFC3339) = %q, want %q", got, want)
+	}
+}
+
+func TestFormatTimestampHonorsEngramTimezone(t *testing.T) {
+	withEngramTimezone(t, "Europe/Madrid") // UTC+2 in May (CEST)
+
+	got := formatTimestamp("2026-05-22T09:56:00Z")
+	want := "22 May 2026 11:56"
+	if got != want {
+		t.Fatalf("formatTimestamp under Europe/Madrid = %q, want %q", got, want)
+	}
+}
+
+func TestFormatTimestampEmptyReturnsDash(t *testing.T) {
+	if got := formatTimestamp(""); got != "-" {
+		t.Fatalf("formatTimestamp(empty) = %q, want %q", got, "-")
+	}
+	if got := formatTimestamp("   "); got != "-" {
+		t.Fatalf("formatTimestamp(whitespace) = %q, want %q", got, "-")
+	}
+}
+
+func TestFormatTimestampUnparseableReturnsRaw(t *testing.T) {
+	// Malformed input must not be lost; the helper returns it as-is so the UI
+	// stays informative even when the source data is unexpected.
+	in := "not-a-timestamp"
+	if got := formatTimestamp(in); got != in {
+		t.Fatalf("formatTimestamp(unparseable) = %q, want %q", got, in)
+	}
+}
+
+func TestFormatTimestampStrEmptyReturnsNever(t *testing.T) {
+	if got := formatTimestampStr(""); got != "Never" {
+		t.Fatalf("formatTimestampStr(empty) = %q, want %q", got, "Never")
+	}
+}
+

internal/mcp/mcp.go

@@ -26,6 +26,7 @@ import (
 	"github.com/Gentleman-Programming/engram/internal/diagnostic"
 	projectpkg "github.com/Gentleman-Programming/engram/internal/project"
 	"github.com/Gentleman-Programming/engram/internal/store"
+	"github.com/Gentleman-Programming/engram/internal/timeutil"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
@@ -981,7 +982,7 @@ func handleSearch(s *store.Store, cfg MCPConfig, activity *SessionActivity) serv
 			fmt.Fprintf(&b, "[%d] #%d (%s) — %s\n    %s\n    %s%s | scope: %s\n",
 				i+1, r.ID, r.Type, r.Title,
 				preview,
-				r.CreatedAt, projectDisplay, r.Scope)
+				timeutil.FormatLocal(r.CreatedAt), projectDisplay, r.Scope)
 
 			// Append relation annotations. Skip orphaned (filtered by store).
 			//
@@ -1546,7 +1547,7 @@ func handleTimeline(s *store.Store, cfg MCPConfig) server.ToolHandlerFunc {
 		// Focus observation (highlighted)
 		fmt.Fprintf(&b, ">>> #%d [%s] %s <<<\n", result.Focus.ID, result.Focus.Type, result.Focus.Title)
 		fmt.Fprintf(&b, "    %s\n", truncate(result.Focus.Content, 500))
-		fmt.Fprintf(&b, "    %s\n\n", result.Focus.CreatedAt)
+		fmt.Fprintf(&b, "    %s\n\n", timeutil.FormatLocal(result.Focus.CreatedAt))
 
 		// After entries
 		if len(result.After) > 0 {
@@ -1597,7 +1598,7 @@ func handleGetObservation(s *store.Store, cfg MCPConfig) server.ToolHandlerFunc
 			obs.ID, obs.Type, obs.Title,
 			obs.Content,
 			obs.SessionID, obsProject+scope+topic, toolName+duplicateMeta+revisionMeta,
-			obs.CreatedAt,
+			timeutil.FormatLocal(obs.CreatedAt),
 		)
 
 		if detErr != nil {

internal/store/store.go

@@ -21,6 +21,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/Gentleman-Programming/engram/internal/timeutil"
 	sqlite "modernc.org/sqlite"
 )
 
@@ -3082,15 +3083,15 @@ func (s *Store) FormatContext(project, scope string) (string, error) {
 				summary = fmt.Sprintf(": %s", truncate(*sess.Summary, 200))
 			}
 			fmt.Fprintf(&b, "- **%s** (%s)%s [%d observations]\n",
-				sess.Project, sess.StartedAt, summary, sess.ObservationCount)
+				sess.Project, timeutil.FormatLocal(sess.StartedAt), summary, sess.ObservationCount)
 		}
 		b.WriteString("\n")
 	}
 
 	if len(prompts) > 0 {
 		b.WriteString("### Recent User Prompts\n")
 		for _, p := range prompts {
-			fmt.Fprintf(&b, "- %s: %s\n", p.CreatedAt, truncate(p.Content, 200))
+			fmt.Fprintf(&b, "- %s: %s\n", timeutil.FormatLocal(p.CreatedAt), truncate(p.Content, 200))
 		}
 		b.WriteString("\n")
 	}

internal/timeutil/timeutil.go

@@ -0,0 +1,49 @@
+package timeutil
+
+import (
+	"os"
+	"time"
+)
+
+// defaultLayout is used by FormatLocal when callers do not care about display style.
+const defaultLayout = "2006-01-02 15:04:05"
+
+// FormatLocal converts a UTC timestamp string to the configured display timezone using
+// the default layout ("2006-01-02 15:04:05"). When ENGRAM_TIMEZONE is unset or invalid
+// it falls back to system local time. Unparseable input is returned as-is.
+//
+// Accepted input layouts: "2006-01-02 15:04:05" (SQLite style), time.RFC3339, time.RFC3339Nano.
+func FormatLocal(utc string) string {
+	return FormatLocalWithLayout(utc, defaultLayout)
+}
+
+// FormatLocalWithLayout is the layout-aware variant of FormatLocal. It applies the same
+// timezone conversion rules and accepts the same input formats, but renders the output
+// with the caller's layout. Use this when a UI surface (e.g. the dashboard) needs a
+// specific display style while still honoring ENGRAM_TIMEZONE.
+//
+// If the input cannot be parsed in any of the accepted layouts, the original string is
+// returned unchanged so callers never lose data on malformed timestamps.
+func FormatLocalWithLayout(utc, layout string) string {
+	for _, in := range []string{
+		"2006-01-02 15:04:05",
+		time.RFC3339,
+		time.RFC3339Nano,
+	} {
+		if t, err := time.Parse(in, utc); err == nil {
+			return toConfiguredLocal(t.UTC()).Format(layout)
+		}
+	}
+	return utc
+}
+
+func toConfiguredLocal(t time.Time) time.Time {
+	tz := os.Getenv("ENGRAM_TIMEZONE")
+	if tz != "" {
+		if loc, err := time.LoadLocation(tz); err == nil {
+			return t.In(loc)
+		}
+	}
+	// Fallback to system local
+	return t.Local()
+}

internal/timeutil/timeutil_test.go

@@ -0,0 +1,69 @@
+package timeutil
+
+import (
+	"os"
+	"testing"
+)
+
+func TestFormatLocal(t *testing.T) {
+	// Original tz
+	oldTz := os.Getenv("ENGRAM_TIMEZONE")
+	defer os.Setenv("ENGRAM_TIMEZONE", oldTz)
+
+	// Set to Bogota
+	os.Setenv("ENGRAM_TIMEZONE", "America/Bogota")
+
+	// UTC time string
+	utcStr := "2026-05-04 12:00:00" // noon UTC
+	// In Bogota (UTC-5), this should be 07:00:00
+	expected := "2026-05-04 07:00:00"
+
+	result := FormatLocal(utcStr)
+	if result != expected {
+		t.Errorf("Expected %s but got %s", expected, result)
+	}
+
+	// Test RFC3339
+	rfcStr := "2026-05-04T12:00:00Z"
+	resultRfc := FormatLocal(rfcStr)
+	if resultRfc != expected {
+		t.Errorf("Expected RFC %s but got %s", expected, resultRfc)
+	}
+
+	// Test invalid
+	invalidStr := "not-a-time"
+	if FormatLocal(invalidStr) != invalidStr {
+		t.Errorf("Expected invalid string to be returned as-is")
+	}
+
+	// Test fallback when env var is empty
+	os.Setenv("ENGRAM_TIMEZONE", "")
+	// When empty, it falls back to system local. It's hard to assert exactly without mocking time.Local,
+	// but we can just ensure it parses successfully and doesn't panic.
+	if FormatLocal(utcStr) == "" {
+		t.Errorf("Expected fallback to format something, got empty string")
+	}
+}
+
+// TestFormatLocalWithLayoutPreservesCallerLayout covers the dashboard use case:
+// UI surfaces pass a friendly layout (e.g. "02 Jan 2006 15:04") and still get
+// ENGRAM_TIMEZONE-aware conversion. The dashboard regression test in
+// internal/cloud/dashboard/helpers_test.go relies on this contract.
+func TestFormatLocalWithLayoutPreservesCallerLayout(t *testing.T) {
+	old := os.Getenv("ENGRAM_TIMEZONE")
+	defer os.Setenv("ENGRAM_TIMEZONE", old)
+	os.Setenv("ENGRAM_TIMEZONE", "America/Bogota") // UTC-5
+
+	// SQLite-style input → friendly dashboard layout output, in Bogota time.
+	got := FormatLocalWithLayout("2026-05-22 12:00:00", "02 Jan 2006 15:04")
+	want := "22 May 2026 07:00"
+	if got != want {
+		t.Errorf("FormatLocalWithLayout = %q, want %q", got, want)
+	}
+
+	// Unparseable input still round-trips unchanged, regardless of layout.
+	raw := "not-a-time"
+	if FormatLocalWithLayout(raw, "02 Jan 2006 15:04") != raw {
+		t.Errorf("expected unparseable input to be returned as-is")
+	}
+}

internal/tui/view.go

@@ -3,8 +3,8 @@ package tui
 import (
 	"fmt"
 	"strings"
-	"time"
 
+	"github.com/Gentleman-Programming/engram/internal/timeutil"
 	"github.com/Gentleman-Programming/engram/internal/version"
 	"github.com/charmbracelet/lipgloss"
 )
@@ -713,16 +713,7 @@ func (m Model) renderObservationListItem(index int, id int64, obsType, title, co
 
 // localTime converts a UTC timestamp string from SQLite to local time for display.
 func localTime(utc string) string {
-	for _, layout := range []string{
-		"2006-01-02 15:04:05",
-		time.RFC3339,
-		time.RFC3339Nano,
-	} {
-		if t, err := time.Parse(layout, utc); err == nil {
-			return t.UTC().Local().Format("2006-01-02 15:04:05")
-		}
-	}
-	return utc // unparseable — return as-is
+	return timeutil.FormatLocal(utc)
 }
 
 func truncateStr(s string, max int) string {