Context: Two small doc gaps that sent me to the source unnecessarily.

1. MelleaSession vs functional.act() — module docstring gives no guidance

Both session.act(...) and mellea.stdlib.functional.act(...) are reachable via completion and look superficially interchangeable. They are not:

• MelleaSession.act takes just the action + options; manages context internally; returns ComputedModelOutputThunk.
• functional.act requires explicit context: Context and backend: Backend arguments and returns a tuple (thunk, Context) — it's the low-level primitive the session wraps.

The act-and-aact.md how-to already labels functional as advanced and says "the session API is simpler" — that's the right signal. But the functional.py module docstring itself ("""Functions for Mellea operations like Instruct, Chat, etc...""") gives no such guidance, and it's what a developer sees first via grep or completion. A developer who finds functional.act there will wire up context/backend by hand and fight the tuple return.

Fix: add a note to functional.py's module docstring: "These are the low-level primitives. For scripts and apps, use MelleaSession (mellea.start_session), which manages context and backend for you. Reach for these only when implementing a custom session or sampling strategy."

2. start_session() explicit form not in any getting-started example

The quickstart and README show start_session() with no arguments. The explicit form start_session("ollama", IBM_GRANITE_4_1_3B) is valid and its signature is in the API reference — but it doesn't appear in any quickstart or getting-started example, so a developer pinning a specific model has to confirm the argument order and the model_ids import path from source.

Fix: add one explicit example to the quickstart immediately after the arg-less form:

from mellea import start_session
from mellea.backends.model_ids import IBM_GRANITE_4_1_3B

# Explicit form — same as default, but pinned for reproducibility:
with start_session("ollama", IBM_GRANITE_4_1_3B) as m:
    ...