Show OTP code validity in frontends

docs/otp.md

@@ -48,3 +48,19 @@ code whose counter update was not committed.
 OTP codes support terminal or secret-safe clipboard presentation. URI output
 supports terminal, clipboard, and the shared storage-owned QR matrix renderer.
 Clipboard and QR requests never print the underlying code or URI as plaintext.
+
+Every generated code carries an `OtpCodeValidity` value from `crates/storage`.
+`Timed { valid_until }` identifies the exclusive Unix-time boundary for TOTP;
+frontends call its `remaining_at` method to present a countdown and request a
+replacement at zero. `CounterBased { counter }` identifies the HOTP counter
+whose increment was committed and must be described as counter-based rather
+than time-limited. Frontends must not recover periods from OTP URIs, decrement
+an assumed interval, or infer the kind from formatted text. This same contract
+is intended for the terminal, desktop, Apple, AutoFill, and watch interfaces.
+
+The CLI preserves code-only standard output for pass-compatible pipelines and
+reports the non-secret validity description on standard error. Clipboard
+lifecycle feedback remains separate, and clipboard-only presentation does not
+echo the code. The TUI observes the system clock during its normal repaint loop,
+asks the storage validity value for the remaining seconds, and refreshes at the
+exact boundary without treating repainting as user activity.