Use this to discover what the library covers before deciding what to
fetch. When the question already names a FinOps domain, phase, persona
or maturity, call ``find_references`` instead of scanning this full
list.

Returns a dict shaped ``{"references": [...], "total": N}`` where each
entry includes ``name``, ``title``, a one-line ``description``, the
discriminating FCP facets (``fcp_domain``, ``fcp_capability``,
``fcp_phases``, ``fcp_personas_primary``, ``fcp_maturity_entry``) and
``approx_tokens``.

Read ``approx_tokens`` before fetching: the library runs from about 2,000
to about 15,000 tokens per file. Above roughly 10,000, prefer
``get_reference(name, section=...)`` and pull the part you need.

Use this when you need the actual content of one known reference,
after ``list_references`` or ``find_references`` told you which one
serves the question. Advisory questions (commitment sizing, chargeback
design, allocation methodology) are served by the reference's decision
rules and worked examples, which a summary does not carry.

Pass ``section`` when the question is narrower than the file. The
``approx_tokens`` hint in the listing tells you when this matters: the
largest references run to about 15,000 tokens and the Azure pattern catalogue
is an enumerated list, so a question about storage lifecycle wants one
section of ``finops-azure-patterns``, not all of it. Omit ``section`` for the whole
file when you need the cross-cutting reasoning.

Args:
    name: Reference name as returned by ``list_references`` (e.g.
        ``"finops-aws"``, ``"finops-genai-capacity"``,
        ``"optimnow-methodology"``).
    section: Optional H2 or H3 heading to return on its own. Matched
        case-insensitively and partially against the headings, so a
        natural phrase works - ``"storage"``, ``"commitment decision
        tree"``. A heading's trailing count is ignored, so
        ``"storage optimization patterns"`` matches
        ``"Storage Optimization Patterns (28)"``. If it matches nothing
        you get the list of available headings back, not the whole file.

Without ``section``, returns ``{"name": ..., "content": "...",
"lines": N}`` where ``content`` is the file verbatim. With ``section``,
returns ``{"name", "title", "section", "section_level", "partial": true,
"content", "lines", "full_lines"}`` where ``content`` is that section
prefixed by the reference's title, plus ``other_matching_sections`` when
the phrase matched more than one heading.

On a miss, returns ``{"error": ..., "suggestions": [...]}``. An unknown
name gives up to three string-distance matches; an unmatched ``section``
gives ``available_sections`` - every heading in the file - so the retry
is exact.

Use this for questions like "how should we size Savings Plans",
"what should Finance own in chargeback", "what does a Crawl-stage org
tackle first" - anything that maps to FinOps Framework facets (domain,
capability, phase, persona, maturity) - and you want only the
references that serve it, instead of scanning the full list.

All filters are optional and combine with AND semantics. String matching
is case-insensitive and exact (not substring). Examples:

- ``find_references(domain="Optimize Usage & Cost")``
- ``find_references(phase="Optimize", persona="Engineering")``
- ``find_references(persona="Engineering", persona_primary_only=True)``
- ``find_references(capability="Rate Optimization")``
- ``find_references(maturity="Crawl")``

Args:
    domain: FinOps Framework domain (e.g. ``"Optimize Usage & Cost"``,
        ``"Quantify Business Value"``, ``"Manage the FinOps Practice"``).
    capability: FinOps capability (matches ``fcp_capability`` and
        ``fcp_capabilities_secondary``).
    phase: FinOps phase (``"Inform"``, ``"Optimize"``, ``"Operate"``).
    persona: Persona (matches ``fcp_personas_primary`` and
        ``fcp_personas_collaborating``).
    maturity: Entry maturity level (``"Crawl"``, ``"Walk"``, ``"Run"``).
    persona_primary_only: when True, ``persona`` matches only the primary
        list. Use it when the default match barely narrows the set -
        broad personas like Engineering collaborate on nearly every file,
        so filtering on collaboration is descriptive, not discriminating.
        ``persona="Engineering", persona_primary_only=True`` is the
        engineering reading list; the default is the everything-they-touch
        view.

Returns ``{"filters": {...}, "references": [...], "total": N}``. A query
that matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage.

Use this to discover which waste patterns have a runbook. When the
question already names a provider, waste category, or confidence tier,
call ``find_playbooks`` instead.

Each playbook is a small (~90-170 line) runbook scoped to one waste
pattern (e.g. ``aws-zombie-nat-gateway``, ``azure-orphan-disks``). Returns
``{"playbooks": [...], "total": N}`` where each entry includes ``name``,
``title``, ``scope`` (aws/azure/gcp/cross-cloud), ``service``,
``waste_category``, ``confidence`` (obvious/likely/possible), and
``approx_tokens`` - the same size hint the reference listing carries, so a
multi-playbook answer can be budgeted before fetching.

Use this when the user asks how to detect, confirm, or fix one specific
named waste pattern (zombie NAT gateway, snapshot sprawl, idle SageMaker
endpoint, ...). It also serves questions about the user's own resources
("which of my X..."): the runbook's detection query is written to be run
in the user's account, so the answer does not depend on access to that
account.

Args:
    name: Playbook slug as returned by ``list_playbooks`` (e.g.
        ``"aws-zombie-nat-gateway"``, ``"azure-orphan-disks"``,
        ``"cross-cloud-untagged-spend-drift"``).

Returns ``{"name": ..., "title": ..., "content": "...", "lines": N}``.
On miss, returns ``{"error": ..., "suggestions": [...]}`` with up to
three string-distance matches so the caller can self-correct.

A host with MCP Apps (SEP-1865) support may render this result via the
linked ``ui://cloud-finops/playbook-viewer`` resource instead of showing
the raw markdown.

Use this for questions like "which VMs are running for nothing",
"why is our NAT bill so high", "my NAT gateway processes 10TB to S3",
"should I delete these old snapshots", "which of our RIs are about to
expire", "what waste can we clean up safely without review" - anything
that names a provider, a waste category, or how confident the
detection needs to be before acting. Patterns
covered include NAT gateways and VPC endpoints, expiring Savings
Plans / RIs / reservations, snapshot sprawl, S3 lifecycle gaps, idle
or stopped VMs, orphaned disks / public IPs / EBS volumes, GPU and
SageMaker sizing, Kubernetes idle capacity, and schedule blindness.

All filters are optional and combine with AND semantics. String matching
is case-insensitive and exact. Examples:

- ``find_playbooks(scope="aws")`` - all AWS-specific playbooks
- ``find_playbooks(waste_category="idle")`` - every idle-resource pattern
- ``find_playbooks(scope="cross-cloud", confidence="obvious")``

Args:
    scope: ``"aws"``, ``"azure"``, ``"gcp"``, or ``"cross-cloud"``.
    service: Provider service exact-match (e.g. ``"AWS NAT Gateway"``).
    waste_category: ``"orphaned"``, ``"idle"``, ``"overprovisioned"``,
        ``"commitment-mismatch"``, ``"schedule-blindness"``,
        ``"modernization"``, ``"ai-ml-inefficiency"``, or ``"egress"``.
    confidence: ``"obvious"`` (single signal is enough),
        ``"likely"`` (two signals required), or ``"possible"``
        (needs human review). From the OptimNow three-tier confidence
        model in `finops-waste-detection-playbooks`.

Returns ``{"filters": {...}, "playbooks": [...], "total": N}``. A query
that matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage.