# find

URL: /chirp-ui/api/find/
Section: api
Description: Fuzzy component discovery over the shipped manifest — ``python -m chirp_ui find``.

Sprint 6 of the agent-grounding-depth epic. The manifest is the registry
projection; this module turns it into a one-liner for humans and agents who
know *what* they want but not the exact BEM block name.

Search model
------------

A component matches a query when the query is a case-insensitive substring of
any of:

* ``name`` — the manifest key, e.g. ``metric-card``
* ``block`` — the BEM block, e.g. ``metric-card`` (usually same as name)
* ``category`` — e.g. ``data-display``, ``feedback``
* ``description`` — the ``{#- chirp-ui: ... -#}`` doc-block text

Query filters (``--category`` etc.) are applied AFTER substring match, so
``find --category=feedback`` lists every component in that category even when
no term is given.

Use ``--authoring=preferred`` to list the registry-blessed primitives agents
should reach for first, or ``--authoring=compatibility`` to audit legacy
helpers retained for existing templates.

Output
------

One line per hit, stable/sorted::

    {name:<30} {category:<16} {first-line-of-description}

Exit code ``0`` always (including zero hits) — this is discovery, not
validation.

See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

---

> For a complete page index, fetch /chirp-ui/llms.txt.

# find

Fuzzy component discovery over the shipped manifest — ``python -m chirp_ui find``.

Sprint 6 of the agent-grounding-depth epic. The manifest is the registry
projection; this module turns it into a one-liner for humans and agents who
know *what* they want but not the exact BEM block name.

Search model
------------

A component matches a query when the query is a case-insensitive substring of
any of:

* ``name`` — the manifest key, e.g. ``metric-card``
* ``block`` — the BEM block, e.g. ``metric-card`` (usually same as name)
* ``category`` — e.g. ``data-display``, ``feedback``
* ``description`` — the ``{#- chirp-ui: ... -#}`` doc-block text

Query filters (``--category`` etc.) are applied AFTER substring match, so
``find --category=feedback`` lists every component in that category even when
no term is given.

Use ``--authoring=preferred`` to list the registry-blessed primitives agents
should reach for first, or ``--authoring=compatibility`` to audit legacy
helpers retained for existing templates.

Output
------

One line per hit, stable/sorted::

{name:<30} {category:<16} {first-line-of-description}

Exit code ``0`` always (including zero hits) — this is discovery, not
validation.

See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

module

Fuzzy component discovery over the shipped manifest — ``python -m chirp_ui find``.

Sprint 6 of the agent-grounding-depth epic. The manifest is the registry
projection; this module turns it into a one-liner for humans and agents who
know *what* they want but not the exact BEM block name.

Search model
------------

A component matches a query when the query is a case-insensitive substring of
any of:

* ``name`` — the manifest key, e.g. ``metric-card``
* ``block`` — the BEM block, e.g. ``metric-card`` (usually same as name)
* ``category`` — e.g. ``data-display``, ``feedback``
* ``description`` — the ``{#- chirp-ui: ... -#}`` doc-block text

Query filters (``--category`` etc.) are applied AFTER substring match, so
``find --category=feedback`` lists every component in that category even when
no term is given.

Use ``--authoring=preferred`` to list the registry-blessed primitives agents
should reach for first, or ``--authoring=compatibility`` to audit legacy
helpers retained for existing templates.

Output
------

One line per hit, stable/sorted::

{name:<30} {category:<16} {first-line-of-description}

Exit code ``0`` always (including zero hits) — this is discovery, not
validation.

See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

components_by_authoring

function

Return manifest component entries with the given authoring hint.

This is the Python API twin of ``python -m chirp_ui find --authoring=...``.
It returns a name-keyed dict in sorted order so downstream agents/tools can
inspect full manifest entries without hand-filtering JSON.

preferred_components

function

Return components marked as preferred authoring vocabulary.

compatibility_components

function

Return compatibility components retained for existing or narrow uses.

search

function

Return ``(name, category, summary)`` rows sorted by name.

format_rows

function

Format rows as an aligned three-column table (no header).

main

function