# Find standards sources

A standards source is a published, versioned setup that a repository can
adopt. Source search finds the sources published on GitHub's
`repo-standards` topic and validates each, so you can choose one before
adopting it. Run it with an [installed CLI](https://repo-standards.com/docs/guides/install/#install-outside-your-project):

```sh
repo-standards source search --json
repo-standards source search --page 2 --json
```

Search queries the public GitHub `repo-standards` topic. It returns JSON with
or without `--json`; the flag also makes failures structured. No Git project is
required. Search changes no project files, executes no author operations or
prerequisite probes, selects no profile, and starts no adoption. It uses the
same external temporary snapshots and tag-observation cache as
[direct inspection](https://repo-standards.com/docs/reference/inspection/#inspect-with-an-already-installed-exact-cli).

For each repository on the requested page, search reads the complete GitHub
release list through Postern, then selects the first published, non-prerelease
release with a stable SemVer tag in API order. It checks that release's immutable Git snapshot through the same
source acquisition and all-profile resolver used by inspection. This is the
first eligible release in GitHub's list, not a guarantee of the highest SemVer.
An invalid or incompatible release is reported explicitly; search does not
silently fall back to older releases. Stable tags without GitHub releases are
still usable through direct inspection but are not discoverable candidates.

| Report field                              | Meaning                                                                                                                                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cliVersion`, `topic`, `notice`           | Validation version, fixed topic and explicit reminder that discovery is not endorsement.                                                                                                                                                                                           |
| `candidates`                              | Sources whose inspected release snapshot validates with this CLI. Each has canonical `repository`, repository `description`, immutable `commit`, `release` (version, name, URL, publication time), source metadata/compatibility and available `profiles`. No profile is selected. |
| `rejected`                                | Unsupported, unavailable, malformed or incompatible candidates, with repository identity, stable error code, reason and any validation details. Includes the release when one was identified.                                                                                      |
| `page`, `totalCount`, `nextPage`          | Requested page, GitHub's count of topic matches before validation, and next page number or `null`. Pages contain up to 30 topic matches, so a page may contain no valid candidates.                                                                                                |
| `incompleteResults`, `searchLimitReached` | GitHub marked its search incomplete, or its count exceeds the 1,000-result search cap. Neither report claims an exhaustive inventory.                                                                                                                                              |

Follow `nextPage` to continue, up to page 34. Repository ordering and counts can
change between requests. Release lists are paginated independently. GitHub
indexing delays and API rate limits apply. Every GitHub REST request uses a
bearer token from `GH_TOKEN`, or otherwise `GITHUB_TOKEN`, when present. Values
are trimmed; empty or whitespace-only values count as absent. A token uses the authenticated API quota; without one,
requests share the anonymous quota. Tokens never appear in reports, caches or
logs, and private sources remain unsupported. Search can consume several requests per candidate because it
validates referenced content rather than trusting topic labels.

Exit status 0 means the search page was processed, including an empty page or
candidate rejections. Exit status 1 means search could not be completed; 2
means invalid CLI arguments. A page-level connection/API failure is explicit
(`SOURCE_UNAVAILABLE`), and malformed search metadata is
`INVALID_SEARCH_RESPONSE`. Candidate diagnostics include `NO_STABLE_RELEASE`,
`UNSUPPORTED_SOURCE`, `INVALID_SOURCE`, `INVALID_STANDARDS` (with precise resolver
details), acquisition integrity errors and `MOVED_TAG`. A candidate rejected for
CLI compatibility may be usable with another compatible exact CLI version;
it is not presented as a valid candidate for the running version.

An exhausted quota (HTTP 429, or 403 with `x-ratelimit-remaining: 0` or
`retry-after`) anywhere in the page request, release lists, or candidate
acquisition aborts the whole page with `QUOTA_EXHAUSTED` and exit status 1;
it is never a candidate rejection. The message names both token variables and
the reset time or retry delay when usable, preferring `retry-after` over
`x-ratelimit-reset` when both arrive. The CLI does not wait or retry
automatically. A 401 with a token reports `SOURCE_UNAVAILABLE`, saying the token
was rejected, with no anonymous retry; other candidate failures remain rejections.

Discovery is not an endorsement, trust decision or assessment of guidance
quality. Review the source, license, scripts and prerequisites yourself. Choose
one source, stable version and complete profile, then
[adopt it](https://repo-standards.com/docs/guides/adopt/), or preview it first with
[`inspect`](https://repo-standards.com/docs/reference/inspection/). A known-source inspection never calls search;
it remains usable when discovery is unavailable. See the
[author publication workflow](https://repo-standards.com/docs/guides/author-a-source/#publish-and-evolve).

GitHub API references: [repository search](https://docs.github.com/en/rest/search/search#search-repositories) and [release listing](https://docs.github.com/en/rest/releases/releases#list-releases).
