​

Architecture And Spec

The project contract now lives directly in Mintlify. Use this page as the operator overview, then read the detailed pages when you need the full constraints:

• Specification
• Architecture

​

Core Product Rule

Plain search must stay close to native GitHub repository search. That means:

• one GitHub repository-search request
• native ordering
• no silent reranking
• no silent metadata enrichment
• no silent README fetching

Anything heavier belongs behind explicit flags.

​

System Shape

The CLI is split into five subsystems:

• command parsing and validation
• auth and host resolution
• native search execution
• enhanced discovery and reranking
• output and error rendering

​

Key Source Files

​

Important Behavioral Constraints

• auth is PAT-only in v1
• host handling is explicit and normalized
• config is conservative and must not silently enable enhanced behavior
• discover mode is bounded, not open-ended
• errors are symbolic plain text on stderr
• structured output must keep stdout clean

​

What Counts As A Contract Change

Treat these as contract-level changes:

• public command surface
• observable output shape
• persistence format
• error semantics
• ranking semantics
• release/distribution behavior

If one of those changes, update:

• the code
• tests
• README
• relevant Mintlify pages
• release runbook when applicable