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

# Core Concepts

> Understanding the fundamental concepts in Ground

# Core Concepts

Ground is built around a few key concepts that work together to provide grounded retrieval.

## Sources

A **source** is a repository, documentation site, or PDF that Ground indexes. Each source has:

* **Type**: `repo` (Git), `docs` (documentation), or `pdf` (uploaded PDF)
* **Format**: For docs, either `html` (web pages) or `openapi` (API specs)
* **URL**: The location to fetch content from
* **Status**: `pending`, `syncing`, `synced`, or `error`

<Info>
  Sources are indexed asynchronously via sync jobs. After creating a source, you must trigger a sync to index its content.
</Info>

## Jobs

A **job** represents a sync operation that fetches, parses, chunks, embeds, and indexes content from a source.

Jobs progress through stages:

1. `queued` → Waiting to be processed
2. `fetch` → Downloading content from the source
3. `parse` → Extracting text from files/pages
4. `chunk` → Splitting content into searchable chunks
5. `embed` → Generating vector embeddings
6. `index` → Storing chunks in the database
7. `finalize` → Updating source metadata

## Chunks

A **chunk** is a piece of indexed content with:

* **Content**: The actual text
* **Embedding**: Vector representation for semantic search
* **Metadata**: Path, language, line numbers, version reference
* **Extra metadata**: For OpenAPI chunks, includes method, path, operation ID

## Search

Ground uses **hybrid search** combining:

1. **Vector similarity**: Finds semantically similar content
2. **Full-text search**: Matches keywords and phrases

Results are scored using a weighted combination (70% vector, 30% text by default).

## Citations

Every search result includes a **citation** with:

* Source name and ID
* File path or URL
* Symbol (function/class name or section heading)
* Line numbers (for code)
* Version reference (commit SHA or doc version)
* Language/chunk type

## Freshness & Staleness

Ground tracks how recent each source's content is:

* **Freshness**: Days since last successful sync
* **Staleness**: When a source exceeds the configured staleness budget
* **Warnings**: Stale results include warnings in the response

## Trust Policy

The **trust policy** controls search behavior:

* **Staleness budget**: How many days before content is considered stale
* **Source priorities**: Weights for different source types (e.g., OpenAPI higher for API questions)
* **Refusal thresholds**: Minimum evidence count/score to answer

## Conflicts

When multiple sources define the same thing differently (e.g., same API endpoint with different schemas), Ground detects and surfaces the **conflict**.

<CardGroup cols={2}>
  <Card title="Sources" icon="database" href="/concepts/sources">
    Deep dive into source types and configuration
  </Card>

  <Card title="Search" icon="search" href="/concepts/search">
    How hybrid search works
  </Card>

  <Card title="Trust Policy" icon="shield" href="/guides/trust-policy">
    Configure staleness and refusal
  </Card>

  <Card title="OpenAPI" icon="file-code" href="/guides/openapi-ingestion">
    Index API specifications
  </Card>
</CardGroup>