> ## Documentation Index
> Fetch the complete documentation index at: https://gitquarry.micr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Specification

> Full product contract for gitquarry v1.

# Specification

This page replaces the former root-level `SPEC.md` file.

## Product Summary

`gitquarry` is a Rust terminal CLI for public GitHub repository search.

The core contract is:

* plain `search "query"` is native GitHub-style repository search
* custom filtering and better discovery exist behind explicit flags
* nothing heavier happens silently

## Command Surface

### Root

* `gitquarry search [OPTIONS] [QUERY]`
* `gitquarry inspect [OPTIONS] <OWNER/REPO>`
* `gitquarry tree [OPTIONS] <OWNER/REPO>`
* `gitquarry code [OPTIONS] <OWNER/REPO> <PATTERN>`
* `gitquarry compare [OPTIONS] <OWNER/REPO>...`
* `gitquarry source path [OPTIONS] <SPEC>`
* `gitquarry recipe run <FILE>`
* `gitquarry mcp`
* `gitquarry agent`
* `gitquarry skills [list]`
* `gitquarry skills get <NAME> [--full]`
* `gitquarry skills path [NAME]`
* `gitquarry auth login [OPTIONS]`
* `gitquarry auth status [OPTIONS]`
* `gitquarry auth logout [OPTIONS]`
* `gitquarry config path`
* `gitquarry config show`
* `gitquarry version`
* `gitquarry --version`
* `gitquarry --generate-completion <bash|zsh|fish|powershell>`

### Global Options

* `--host <HOST_OR_URL>`
  * accept bare hostnames or full URLs
  * normalize internally
  * default host is `github.com` unless overridden by config

## Auth

### Scope

* auth is always required
* v1 is PAT-only
* device flow is out of scope for v1
* v1 is read-only and public-repos-only

### Commands

* `auth login`
  * interactive guided PAT setup
  * teaches the user how to create a PAT
  * recommends fine-grained PATs when possible
  * validates the PAT immediately
  * stores credentials per host
* `auth status`
  * shows whether the current effective host has a saved PAT
* `auth logout`
  * deletes the PAT for the current effective host

### Storage

* secrets are stored in the OS credential store by default
* env vars override saved credentials
* if secure storage is unavailable, insecure file fallback is allowed only with explicit opt-in and warning
* PATs are stored per host, not globally

## Config

### Location

* store config in a standard per-user config path
* do not store config in the repo or current working directory

### Allowed Saved Defaults

* `host`
* `format`
* `limit`
* `progress`
* color preference

### Disallowed Saved Defaults

These must remain explicit per command:

* `mode`
* `rank`
* `depth`
* `readme`
* `explain`
* blended ranking weights
* discovery-only engine knobs

Checked-in recipes may contain these values because they are explicit, reviewed inputs to `recipe run`, not hidden saved defaults.

## Search

### Synopsis

```bash theme={null}
gitquarry search [OPTIONS] [QUERY]
```

### Base Behavior

* if the user passes no enhancement flags, search behaves as close to native GitHub repository search as possible
* default output format is `pretty`
* default result limit is `10`
* empty query is invalid in plain native search
* `--plan` prints the compiled search plan without auth resolution or network requests
* probe flags add explicit evidence to final results but do not change order or ranking

### Output Formats

* `pretty` - default
* `json`
* `toon`
* `compact`
* `csv`

### Pretty Output Visual Default

* the default accent color for human-facing `pretty` output is electric blue
* the exact electric-blue shade does not need to be fixed in v1 as long as it stays in that visual family
* ANSI color choices such as `21` or `27` are acceptable defaults
* users may override color preference through config or terminal settings where supported

### Retrieval Modes

* `--mode native`
  * one native GitHub repository search only
* `--mode discover`
  * explicit enhanced retrieval
  * uses staged candidate collection and local reranking

Default:

* no `--mode` flag -> native behavior

### Rank Modes

* `--rank native`
* `--rank query`
* `--rank activity`
* `--rank quality`
* `--rank blended`

Rules:

* no enhancement flags -> effective rank is native
* `--mode discover` with no `--rank` -> default to `blended`
* `--rank` never changes retrieval mode
* `--sort` never changes rank mode

### Native Ordering

`--sort` is reserved for native GitHub-like retrieval ordering.

Supported values:

* `best-match`
* `stars`
* `updated`

Rules:

* in `--rank native`, final output order follows native ordering and `--sort`
* in non-native rank modes, `--sort` influences candidate retrieval only; final displayed order comes from the selected rank mode

### Structured Filter Flags

#### Owner / Visibility

* `--user <USER>`
* `--org <ORG>`
* `--archived <true|false>`
* `--template <true|false>`
* `--fork <false|true|only>`

#### Metadata / Classification

* `--language <LANG>` repeatable
* `--topic <TOPIC>` repeatable
* `--license <LICENSE>` repeatable

#### Numeric Ranges

* `--min-stars <N>`
* `--max-stars <N>`
* `--min-forks <N>`
* `--max-forks <N>`
* `--min-size <N>`
* `--max-size <N>`

#### Absolute Date Filters

* `--created-after <YYYY-MM-DD>`
* `--created-before <YYYY-MM-DD>`
* `--updated-after <YYYY-MM-DD>`
* `--updated-before <YYYY-MM-DD>`
* `--pushed-after <YYYY-MM-DD>`
* `--pushed-before <YYYY-MM-DD>`

#### Relative Date Filters

* `--created-within <DURATION>`
* `--updated-within <DURATION>`
* `--pushed-within <DURATION>`

Relative duration syntax:

* `12h`
* `30d`
* `8w`
* `6m`
* `1y`

### Filter Semantics

* repeated structured flags use AND semantics
* OR semantics remain available only through raw GitHub query syntax in the query string
* `--topic` is GitHub-native topics only
* custom label/category matching is not exposed as a first-class flag
* custom label/category interpretation is query-driven and only available in enhanced/discovery mode

### Native vs Post-Filter Behavior

Compile directly into GitHub-native search when possible:

* user/org
* archived
* template
* fork
* language
* topic
* license
* stars
* forks
* size
* created
* pushed
* sort

Apply post-retrieval using repo metadata:

* `updated-*`

### Empty Query Rules

* plain native search requires a query
* empty query is allowed only in explicit discovery-oriented usage

Examples:

* valid: `gitquarry search "rust sdk"`
* valid: `gitquarry search --mode discover --topic cli --sort updated`
* invalid: `gitquarry search`

### Raw Query Plus Structured Flags

The free-text query is the base query. Structured flags append constraints.

If the user manually writes a raw GitHub qualifier in the query and also passes an overlapping structured flag, fail clearly instead of guessing.

Examples of conflicts:

* `language:rust` plus `--language go`
* `topic:cli` plus `--topic sdk`
* `stars:>100` plus `--min-stars 200`

### Discovery Depth

Discovery depth is discover-only.

* `--depth quick`
* `--depth balanced`
* `--depth deep`

Do not allow `--depth` outside discover mode.

Default in discover mode:

* `balanced`

### Candidate Pool Targets

Discovery uses a deduped candidate pool before final reranking.

Defaults:

* `quick`: target `max(25, limit * 3)`, cap `100`
* `balanced`: target `max(50, limit * 5)`, cap `200`
* `deep`: target `max(100, limit * 8)`, cap `400`

### Discovery Retrieval Behavior

Discovery retrieval is staged and bounded.

#### Quick

* seed with one native GitHub repository search only
* no extra fan-out beyond the initial retrieval
* rerank only the returned candidate set

#### Balanced

* seed with one native GitHub repository search
* if the deduped pool is below target:
  * run the same search with `sort=updated`
  * run one recency-biased shard using a recent `pushed` bucket
* stop as soon as the target pool is reached

#### Deep

* includes balanced behavior
* if still below target:
  * add older `pushed` bucket searches
  * add star-bucket shard searches if the user did not already constrain stars
* stop as soon as the target pool is reached

### README Enrichment

* `--readme` is explicit
* no README fetching occurs by default
* `--readme` never changes retrieval mode by itself
* README is enrichment-only, not candidate retrieval

README window:

* metadata ranking runs first
* then README enrichment inspects only the top candidate window
* default window = `min(20, max(limit * 2, 10))`

### Explainability

* `--explain` is explicit
* without `--explain`, no ranking reasons are shown
* in native mode, `--explain` is minimal or unsupported
* in enhanced modes, `--explain` can show:
  * matched surfaces
  * query score
  * activity score
  * quality score
  * blended score
  * effective weights
  * key contributing signals

### Blended Ranking Weights

Weight flags:

* `--weight-query <0.0..3.0>`
* `--weight-activity <0.0..3.0>`
* `--weight-quality <0.0..3.0>`

Rules:

* weight flags are valid only with `--rank blended`
* each value must be in the inclusive range `0.0` to `3.0`
* default weight for each component is `1.0`
* all-zero weight sets are invalid

## Scoring

### Query Score

Literal-first only. No automatic synonym expansion in v1.

Use weighted literal matching across:

* repository name
* description
* topics
* README only if `--readme` is enabled

### Activity Score

Use only:

* `pushed_at`
* `updated_at`
* release recency
* archived penalty

### Quality Score

Use only:

* stars
* forks
* contributor count
* license presence
* README presence
* template status

No issue-based signals in v1. No momentum or trending signals in v1.

### Blended Score

For `--rank blended`, compute a normalized weighted average:

`(wq * query + wa * activity + wql * quality) / (wq + wa + wql)`

Only include components whose weight is greater than zero.

## Inspect

### Synopsis

```bash theme={null}
gitquarry inspect [OPTIONS] <OWNER/REPO>
```

### Behavior

* accept only explicit `owner/repo`
* no cross-command memory
* default is metadata-first
* README is optional and explicit

### Defaults

* output format defaults to `pretty`
* default content includes:
  * full name
  * URL
  * description
  * stars
  * forks
  * language
  * topics
  * license
  * created / updated / pushed
  * archived / template / fork status
  * open issues count
  * latest release summary when cheaply available

### Inspect Flags

* `--readme`
* `--format pretty|json|toon|compact|csv`

## Tree

### Synopsis

```bash theme={null}
gitquarry tree [OPTIONS] <OWNER/REPO>
```

### Behavior

* fetch a repository tree through the GitHub API without cloning
* default to the repository default branch
* support explicit `--reference`
* support path glob, text, and depth filtering before rendering

## Code

### Synopsis

```bash theme={null}
gitquarry code [OPTIONS] <OWNER/REPO> <PATTERN>
```

### Behavior

* fetch a repository tree, filter candidate blobs, and fetch bounded file contents
* support literal and regex matching
* support path glob filters, context lines, match limits, and maximum file size
* do not clone repositories

## Compare

### Synopsis

```bash theme={null}
gitquarry compare [OPTIONS] <OWNER/REPO>...
```

### Behavior

* accept only explicit `owner/repo` inputs
* preserve input order
* fetch repository metadata, latest release, and contributor count for each repository
* include README only with `--readme`
* include tree counts only with `--tree-summary`
* do not discover repositories or compute a trust score

## Recipe

### Synopsis

```bash theme={null}
gitquarry recipe run <FILE>
```

### Behavior

* read one TOML recipe file
* map recipe keys directly to `search` flags
* reject unknown keys with `E_RECIPE_INVALID`
* never read credentials from recipe files
* host precedence is CLI `--host`, then recipe `host`, then saved config, then `github.com`

## MCP

### Synopsis

```bash theme={null}
gitquarry mcp
```

### Behavior

* run a stdio JSON-RPC server for MCP clients
* support `initialize`, `tools/list`, and `tools/call`
* expose search, inspect, tree, code, compare, and skill tools
* return tool output as MCP text content
* use the same credential and host resolution as the CLI
* keep diagnostics and errors out of tool content

## Source

### Synopsis

```bash theme={null}
gitquarry source path [OPTIONS] <SPEC>
```

### Behavior

* source fetching is explicit and never happens during `search` or `inspect`
* `source path` delegates retrieval and caching to `opensrc path`
* stdout is the resolved source path only
* `opensrc` progress and errors stay on stderr
* if `opensrc` is unavailable, fail with `E_SOURCE_UNAVAILABLE`
* if `opensrc` runs and fails, fail with `E_SOURCE_FETCH`

### Source Flags

* `--cwd <PATH>`
* `--verbose`

## Progress

* progress output goes to `stderr` only
* default progress mode is `auto`
* support `--progress auto|on|off`
* in `auto`, show progress only when `stderr` is a TTY
* no progress is written to stdout
* prefer phase-based progress and counts over fake ETA
* show ETA only for bounded loops where estimation is defensible

## Advanced Engine Flags

* `--concurrency <N>`
  * discover or enrichment only
  * default `1`
  * error outside explicit discovery or enrichment usage

Other engine internals remain internal in v1.

## Error Handling

* fail on the first clear error
* print plain text to `stderr`
* include a stable symbolic error code
* exit code `1`

Examples:

* `E_FLAG_REQUIRES_MODE: --concurrency requires --mode discover`
* `E_FLAG_CONFLICT: --created-after cannot be combined with --created-within`
* `E_AUTH_REQUIRED: auth required for host github.example.com; run gitquarry auth login --host github.example.com`

Errors are never emitted as JSON in v1.

## Version And Completion

* support both `version` and root `--version`
* include shell completion generation in v1
* support `bash|zsh|fish|powershell`
* include embedded, version-matched agent skill guidance through `agent` and `skills`