Prompt Session.doc

# `Prompt sessions` – runtime state for conversational chats

This document complements the inline `odoc` comments of
`session.{mli,ml}` and `session_store.{mli,ml}` with a higher-level
overview, rationale, and concrete examples that do **not** belong in
the terse API reference.

Table of contents
-----------------

1. Rationale & big picture
2. Data model
3. CLI integration
4. Public API walk-through
5. Persistence format & versioning
6. FAQ & troubleshooting

------------------------------------------------------------------------

1  Rationale & big picture
---------------------------------

Historically *ochat* treated prompt files (`*.chatmd`) as **immutable**
specifications of a conversation: you started `chat_tui`, chatted for a
while, and then all messages vanished when the process ended.

`Prompt sessions` promote the **runtime state** to a first-class object
that can be *saved*, *restored*, and migrated across schema versions.
They complement – but never replace – the original prompt file which
remains the authoritative declaration of the *initial* system & user
messages.

In practice this means:

* Start a new session → `snapshot.bin` is created under
  `~/.ochat/sessions/<session-id>/`.
* Quit the TUI gracefully → the session snapshot is updated.
* Restart the TUI with the same `--session` flag (or derived ID) → the
  conversation reappears exactly where you left off.

The mechanism is generic and future-proof: alternative front-ends such
as a web UI can consume the same `Session` API without pulling the TUI
stack.

------------------------------------------------------------------------

2  Data model
-------------