docs: add Args/Returns sections to public function docstrings

[planetf1]

Background

The API reference renders docstring Args: and Returns: sections as structured
parameter lists beneath each function signature. Without them, callers see the
signature type annotations but no explanation of what each parameter means or what
the return value represents — which is the main value the API reference provides
over reading the source directly.

Note: The audit tooling used here is being introduced in
PR #611 and may not
yet be on main. Merge that PR before running the commands below.

How the pipeline uses Args/Returns:
mdxify (step 1 of the pipeline) reads Google-style docstring sections and emits
them as **Args:** / **Returns:** bullet lists in the generated MDX. If the
section is absent the bullet list is simply omitted. The function signature (from
the type annotations) is always shown regardless, so the rendered page is not
broken — it is just less useful.

Scope: documented public symbols only.
This issue tracks only functions and methods that are already surfaced in the
API reference — public, non-_ prefixed, non-alias symbols in mellea/ and
cli/ that have generated MDX pages. Private helpers, internal utilities, and
test code are out of scope. The audit tool enforces this automatically by
cross-referencing the generated docs directory.

What is expected:

• Args: section for every public function or method that has one or more
  parameters beyond self/cls.
• Returns: section for every public function or method whose return annotation
  is non-trivial (i.e. not None or NoReturn).
• Google-style format is the project standard:

  def generate(self, action: Component, ctx: Context) -> tuple[Output, Context]:
      """Generate a model output from a context.
  
      Args:
          action: The component to generate from. Must be the last item of the
              context — pass it separately rather than including it in ctx.
          ctx: The preceding context.
  
      Returns:
          A (output_thunk, updated_context) tuple.
      """

How to find gaps:

# Top-level public symbols (default — matches the counts below)
uv run poe apidocs-quality

# Also include public class methods
uv run python tooling/docs-autogen/audit_coverage.py \
    --docs-dir docs/docs/api --quality

# Save full per-symbol list to JSON
uv run python tooling/docs-autogen/audit_coverage.py \
    --docs-dir docs/docs/api --quality --no-methods --output report.json

---

Scope

Audit run against the current codebase (documented public top-level symbols,
--no-methods) found 88 functions missing an Args section and 80 missing
a Returns section (some overlap) across 141 of 320 documented symbols.
Breakdown by package area:

Package area	Missing Args	Missing Returns
mellea.formatters.granite	36	26
mellea.stdlib.components	8	8
mellea.backends.tools	7	5
mellea.stdlib.requirements	5	7
mellea.stdlib.functional	4	4
mellea.backends.bedrock	3	3
mellea.backends.kv_block_helpers	3	3
mellea.helpers.openai_compatible_helpers	3	3
cli.alora.commands	3	—
cli.eval.runner	3	2
others	11	19

mellea.formatters.granite accounts for roughly 40% of all gaps and is the
highest-value area to address first. Public class methods are a further source
of gaps not counted above — run uv run poe apidocs-quality without
--no-methods to surface those.

---

Priority

1. mellea.formatters.granite — largest cluster, most likely to be reached
   by users working with formatters. 36 Args + 26 Returns gaps.
2. mellea.stdlib.functional — the primary user-facing functional API
   (chat, achat, validate, avalidate). Small count, high visibility.
3. mellea.stdlib.requirements / mellea.stdlib.components — stdlib is
   heavily used; these gaps make the reference noticeably incomplete.
4. mellea.backends.* — lower priority for end users (backends are usually
   selected by name, not called directly), but worthwhile for completeness.
5. cli.* — CLI commands are documented via --help as well; lower urgency.

---

Verification

After adding sections, re-run the audit to confirm counts drop:

uv run poe apidocs-quality