docs: add config-reference.md documenting the full YAML schema (#112)

[PrinceThummar011]

Summary

Adds a dedicated configuration reference page (docs/config-reference.md)
that documents the complete YAML schema used by OpenAgent Eval, sourced
directly from the Pydantic models in openagent_eval/config/models.py.

Closes #112

What's included

• Full field-by-field documentation for all top-level config sections:
  dataset, llm, retriever, metrics, report, corpus, and global
• For each field: type, default value, required/optional status,
  constraints, and description
• Sub-section coverage for nested objects (e.g. retriever.embedder)
• A runnable "Quick Start" example combining all sections into one
  working config.yaml
• Realistic, working YAML snippets per section (not placeholder values)

Changes

• Added: docs/config-reference.md
• Updated: mkdocs.yml — registered the new page under the Guide
  nav section as "Configuration Reference"

Validation

• uv run mkdocs build --strict passes with no broken links or nav errors
• Every table field cross-checked against openagent_eval/config/models.py
• No source files (models.py, config.yaml) were modified — docs-only change

Notes for reviewers

All field descriptions, types, and defaults were pulled directly from
docstrings and field definitions in models.py — nothing was guessed or
fabricated. Flagging for a maintainer's confirmation pass in case any
nested/less-common field's intent needs clarification.

[Copilot]

Pull request overview

Adds a new documentation page that serves as a single reference for OpenAgent Eval’s config.yaml schema (intended to mirror the Pydantic models), and wires it into the MkDocs navigation so users can find it under the Guide section.

Changes:

• Added docs/config-reference.md documenting config sections/fields, defaults, constraints, and examples.
• Added a quick-start full config example to make the schema easier to adopt.
• Registered the new page in mkdocs.yml nav under Guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
mkdocs.yml	Adds the “Configuration Reference” page to the Guide navigation.
docs/config-reference.md	New config schema reference page with tables and examples for each config area.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (6)

docs/config-reference.md:257

• The heading ## global`` reads like there is a global: YAML section, but these settings are actually top-level fields on the root `Config` model (there is no `global` key). Renaming the section title will prevent users from trying `global:` in their YAML.

## `global`

Global settings configure overall execution and concurrency behavior. These fields are defined directly at the top level of `config.yaml`.

docs/config-reference.md:136

• The retriever.provider field is required when a retriever: block is provided. The effective default of chroma comes from the top-level Config default factory when the entire retriever section is omitted, not from a default value on the provider field itself. As written, the row suggests provider has a default even inside an explicitly-provided retriever: block.

| `provider` | `str` | `"chroma"` | Yes | Retriever provider name (e.g., `chroma`, `memory`, `qdrant`, `pinecone`, `weaviate`, `faiss`, `pgvector`, `elasticsearch`, `bm25`, `http`, `mock`). |

docs/config-reference.md:227

• In the Pydantic schema, corpus.checks is list[CorpusCheckType] (an enum), not list[str]. Updating the type here keeps the reference aligned with openagent_eval/config/models.py.

| `checks` | `list[str]` | `["contradiction", "staleness", "duplicate", "coverage"]` | No | Corpus health checks to run. Allowed values: `"contradiction"`, `"staleness"`, `"duplicate"`, `"coverage"`. |

docs/config-reference.md:90

• dataset.format supports pdf in addition to json, jsonl, csv, and hf (the dataset loader also auto-detects .pdf by extension when format is omitted). The allowed-values list should include pdf to match actual supported formats.

| `format` | `str \| None` | `None` | No | Dataset format (`json`, `jsonl`, `csv`, `hf`). Auto-detected if omitted. |

docs/config-reference.md:114

• llm.api_key only falls back to an environment variable for providers that have an env var mapping (e.g., openai/gemini/anthropic/groq/openrouter). Wording this as “when supported” avoids implying ollama/mock use an env var.

| `api_key` | `SecretStr \| None` | `None` | No | API key string (must be at least 10 characters if specified). Falls back to provider environment variable if omitted. |

docs/config-reference.md:203

• This table row is missing a trailing |, which breaks the Markdown table formatting for the report section.

| `output` | `OutputFormat` | `"terminal"` | No | Output format for reports. Allowed values: `"terminal"`, `"markdown"`, `"html"`, `"json"`. 

[github-actions]

🎉 Congratulations @PrinceThummar011!

Your pull request has been successfully merged into main. 🚀

Thank you for contributing to OpenAgentHQ and helping improve the project.

We truly appreciate your contribution and hope to see you back with more amazing PRs!

Happy Open Sourcing! ❤️