timefmt

Documentation

Overview

Package timefmt is the single seam for user-facing time rendering. Every surface that prints a wall-clock instant formats it here, so the policy lives in one place instead of being re-decided per call site:

• AGENT-PARSED surfaces (search results, the outline header, live list + stream, any --json payload): UTC with an explicit marker — RFC3339 "Z" for full instants, "HH:MM:SSZ" for bare clocks. An agent must never have to guess the zone of a timestamp it is about to reason over.
• HUMAN browse tables and `archive status`: local time with the zone abbreviation spelled out (e.g. "2026-01-02 15:04 PST") — friendly to read, still unambiguous.

JSON payloads that carry a source-recorded ISO string verbatim (message ts_iso from the transcript record) already satisfy the marked-UTC policy at the source and are passed through unchanged; UTCFromISO is the display-side normalizer for those strings.

Index

• func Local(t time.Time) string
• func UTC(t time.Time) string
• func UTCClock(t time.Time) string
• func UTCFromISO(iso string) string
• func UTCShort(t time.Time) string
• func UTCShortFromISO(iso string) string

Functions

func Local

func Local(t time.Time) string

Local renders t in local time with the zone abbreviation ("2026-01-02 15:04 PST") — the format for human browse tables and `archive status`.

func UTC

func UTC(t time.Time) string

UTC renders t as a marked-UTC RFC3339 instant ("2026-01-02T15:04:05Z") — the format for agent-parsed surfaces.

func UTCClock

func UTCClock(t time.Time) string

UTCClock renders t's wall-clock as marked UTC ("15:04:05Z") — for compact per-message clocks on agent-parsed surfaces (live stream).

func UTCFromISO

func UTCFromISO(iso string) string

UTCFromISO normalizes a stored ISO timestamp string to the marked-UTC display form ("2026-01-02T15:04:05Z"). An empty or unparseable input is returned verbatim — the seam never invents a time it cannot read.

func UTCShort

func UTCShort(t time.Time) string

UTCShort renders t as a marked-UTC date and minute ("2026-01-02 15:04Z") — the compact form for dense listings that still must not be ambiguous.

func UTCShortFromISO

func UTCShortFromISO(iso string) string

UTCShortFromISO normalizes a stored ISO timestamp to the compact marked-UTC display form ("2026-01-02 15:04Z"). Like UTCFromISO, an empty or unparseable input is returned verbatim rather than guessed at.