docs: document pgvector's 2000-dim HNSW limit for embedding config

[LazyEngineer99]

What

VECTOR_DIMENSIONS has no upper-bound validation at config-load time. Some
embedding models default to output dimensions higher than pgvector's HNSW
index hard limit (2000) — e.g. Gemini's gemini-embedding-001 defaults to
3072. If you switch to such a model without explicitly setting
VECTOR_DIMENSIONS to a supported value, the failure only shows up later,
at index creation, with no indication of why.

This documents the limit directly next to VECTOR_DIMENSIONS in
config.toml.example, and adds a dedicated [embedding] entry to the
README's config section list (it was previously folded into [app]'s
description, but [app] has no embedding-related keys — that line was
stale).

Why

Ran into this directly running a self-hosted instance with Gemini as the
embedding provider — nothing in the docs or code warns about the 2000-dim
ceiling before you hit it.

Testing

• Verified config.toml.example still loads correctly against the real
  AppSettings pydantic schema (docker run ... python3 -c "from src.config import settings; ...").
• README.md passes markdownlint-cli2 clean.
• Docs-only change, no code paths touched.

Summary by CodeRabbit

• Documentation
  • Clarified embedding configuration requirements, including the 2,000-dimension limit imposed by vector indexing.
  • Added guidance for embedding models with higher default dimensions, including examples of when you must set dimensions explicitly.
  • Explained how Matryoshka-compatible embeddings behave when dimensions are configured (truncation vs. failure).
  • Updated the configuration reference to list embedding settings separately.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dccf9de2-e02a-48db-9e6b-3653ee6f2cf6

📥 Commits

Reviewing files that changed from the base of the PR and between c621e13 and 7ff0a0e.

📒 Files selected for processing (1)

• config.toml.example

🚧 Files skipped from review as they are similar to previous changes (1)

• config.toml.example

---

Walkthrough

Configuration documentation separates embedding settings from the app section and documents the VECTOR_DIMENSIONS limit, model guidance, and truncation behavior.

Changes

Embedding dimension documentation

Layer / File(s)	Summary
Document VECTOR_DIMENSIONS constraint README.md, config.toml.example	The configuration reference and example comments document the pgvector HNSW limit of 2000 dimensions, explicit settings for higher-dimensional models, and truncation for compatible embeddings.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Poem

I’m a bunny with settings to share,
Two thousand dimensions fit with care.
Models may stretch, but trim the row,
The README tells which way to go.
Hop, hop—clear configs grow!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main documentation change about pgvector’s 2000-dimension HNSW limit for embedding config.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@config.toml.example`:
- Around line 70-72: Revise the VECTOR_DIMENSIONS comment in the configuration
example to state that values above 2000 may be rejected during startup
configuration validation or by pgvector during index creation, rather than
implying pgvector is the only failure point.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2e03fd38-959c-459c-89c6-d475e4d4e1c7

📥 Commits

Reviewing files that changed from the base of the PR and between 73453f8 and c621e13.

📒 Files selected for processing (2)

• README.md
• config.toml.example