docs: standardize public API docstrings on NumPy style

[davidberenstein1957]

Feature Request

Pick one docstring style for public APIs and make CONTRIBUTING + in-repo contributor rules agree. Prefer NumPy-style (already required by .cursor/rules/documentation.mdc).

Motivation

Public modules mix NumPy and Google styles; agent rules conflict. Reviews bikeshed formatting instead of behavior.

Implementation plan

1. CONTRIBUTING: “Public APIs use NumPy-style docstrings.”
2. Align/remove in-repo rules that still say Google-style for this repo.
3. Touch one public symbol in the PR as the exemplar (no repo-wide rewrite).

Canonical template (copy into CONTRIBUTING)

async def vulnerability_scan(
    target: Target,
    description: str,
    languages: list[str],
    max_scenarios: int | None = None,
) -> SuiteResult:
    """Generate and run the standard vulnerability scan suite.

    Parameters
    ----------
    target : Target
        System under test (sync or async callable).
    description : str
        Natural-language description of the agent under test.
    languages : list of str
        BCP-47 language codes the agent is expected to handle.
    max_scenarios : int, optional
        Upper bound on scenarios across generators. ``None`` uses the
        active preset / per-generator defaults.

    Returns
    -------
    SuiteResult
        Completed suite result (also printed when ``verbose=True``).

    Examples
    --------
    >>> async def echo(inputs: str) -> str:
    ...     return inputs
    >>> result = await vulnerability_scan(
    ...     echo, "A demo agent", ["en"], max_scenarios=5
    ... )
    >>> isinstance(result.pass_rate, float)
    True
    """

Avoid (Google-style) for new public APIs

"""Generate and run the scan.

Args:
    target: System under test.
    description: Agent description.

Returns:
    SuiteResult for the run.
"""

Acceptance criteria

• CONTRIBUTING documents NumPy as the public API standard
• No in-repo contributor rule still mandates Google-style here
• At least one touched public module demonstrates the format

Out of scope

• Mass-rewriting private helpers
• pydocstyle CI (optional follow-up)

[linear-code]

OSS-105