feat: expand configuration documentation and enhance native Postgres support

- Updated mkdocs.yml to include a comprehensive configuration reference section with detailed navigation.
- Added new configuration files for native Postgres support in Docker, allowing for host-installed Postgres connections.
- Enhanced start.sh to include functions for checking native Postgres readiness and improved handling of Docker services.
- Introduced new configuration parameters and documentation for embedding models, chunking, and enrichment.
- Updated GitHub Actions workflow to automate the generation of configuration reference documentation.

Author: DMontgomery40

.github/workflows/docs-automation.yml

@@ -33,7 +33,13 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install project dependencies (uv)
+        run: uv sync --frozen
 
       - name: Install dependencies
         run: |
@@ -81,6 +87,11 @@ jobs:
           echo "Using base ref: $BASE"
           python scripts/docs_ai/generate_docs_from_diff.py --base "$BASE" --llm openai --apply
 
+      - name: Generate config reference docs (Pydantic + glossary)
+        run: |
+          uv run python scripts/generate_config_reference_docs.py --clean
+          git add mkdocs/docs/reference/config
+
       - name: Upload patch (best-effort)
         if: always()
         uses: actions/upload-artifact@v4

data/glossary.json

@@ -1822,6 +1822,28 @@
         }
       ]
     },
+    {
+      "term": "MLX Embedding Model",
+      "key": "EMBEDDING_MODEL_MLX",
+      "definition": "MLX model identifier when EMBEDDING_TYPE=mlx. Runs locally on Apple Silicon via MLX/Metal for very fast embedding inference. Default: \"mlx-community/all-MiniLM-L6-v2-4bit\". The model is downloaded on first use and cached locally. Changing this requires a full reindex (embeddings are not comparable across models).",
+      "category": "embedding",
+      "related": [],
+      "links": [],
+      "badges": [
+        {
+          "text": "Metal GPU",
+          "class": "info"
+        },
+        {
+          "text": "Free (no API)",
+          "class": "info"
+        },
+        {
+          "text": "Requires reindex",
+          "class": "reindex"
+        }
+      ]
+    },
     {
       "term": "Embedding Max Retries",
       "key": "EMBEDDING_RETRY_MAX",
@@ -1889,7 +1911,7 @@
     {
       "term": "Embedding Provider",
       "key": "EMBEDDING_TYPE",
-      "definition": "Selects the embedding provider for dense vector search. Also determines the token counter used during code chunking, which affects chunk boundaries and splitting behavior.\n\n• openai — strong quality, paid (cl100k tokenizer)\n• voyage — strong retrieval, paid (voyage tokenizer)\n• mxbai — OSS via SentenceTransformers\n• local — any HuggingFace SentenceTransformer model\n• gemini — Google Gemini embeddings\n\nNote: Changing this setting affects both retrieval quality AND how code is split into chunks during indexing. A reindex is required after changing.",
+      "definition": "Selects the embedding provider for dense vector search. Also determines the token counter used during code chunking, which affects chunk boundaries and splitting behavior.\n\n• openai — strong quality, paid (cl100k tokenizer)\n• voyage — strong retrieval, paid (voyage tokenizer)\n• mlx — Apple Silicon local embeddings via MLX/Metal (fast)\n• mxbai — OSS via SentenceTransformers\n• local — any HuggingFace SentenceTransformer model\n• gemini — Google Gemini embeddings\n\nNote: Changing this setting affects both retrieval quality AND how code is split into chunks during indexing. A reindex is required after changing.",
       "category": "embedding",
       "related": [],
       "links": [

data/models.json

@@ -658,6 +658,16 @@
       "dimensions": 384,
       "notes": "BGE-small-en local"
     },
+    {
+      "provider": "mlx",
+      "family": "mlx-community/all-MiniLM-L6-v2-4bit",
+      "model": "mlx-community/all-MiniLM-L6-v2-4bit",
+      "components": ["EMB"],
+      "unit": "1k_tokens",
+      "embed_per_1k": 0.0,
+      "dimensions": 384,
+      "notes": "MLX MiniLM embeddings (Metal GPU)"
+    },
     {
       "provider": "huggingface",
       "family": "BAAI/bge-reranker-v2-m3",

infra/docker-compose.native-postgres.yml

@@ -0,0 +1,22 @@
+services:
+  # Use host-installed Postgres (pgvector) via host.docker.internal.
+  # This keeps Neo4j/observability in Docker but eliminates the Docker Postgres VM overhead.
+  api:
+    environment:
+      POSTGRES_HOST: host.docker.internal
+      POSTGRES_PORT: ${POSTGRES_PORT:-5432}
+      NEO4J_URI: bolt://neo4j:7687
+    # Override depends_on to avoid pulling up the docker Postgres service.
+    depends_on:
+      - neo4j
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  postgres-exporter:
+    environment:
+      DATA_SOURCE_NAME: "postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@host.docker.internal:${POSTGRES_PORT:-5432}/${POSTGRES_DB:-tribrid_rag}?sslmode=disable"
+    # Override depends_on to avoid pulling up the docker Postgres service.
+    depends_on: []
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+

mkdocs.yml

@@ -128,7 +128,36 @@ nav:
       - Indexing pipeline: indexing.md
       - Corpus vs repo_id: guides/corpus.md
   - Reference:
-      - Configuration: configuration.md
+      - Config API & workflow: configuration.md
+      - Config reference:
+          - Overview: reference/config/index.md
+          - retrieval: reference/config/retrieval.md
+          - scoring: reference/config/scoring.md
+          - layer_bonus: reference/config/layer_bonus.md
+          - embedding: reference/config/embedding.md
+          - tokenization: reference/config/tokenization.md
+          - chunking: reference/config/chunking.md
+          - indexing: reference/config/indexing.md
+          - graph_storage: reference/config/graph_storage.md
+          - graph_indexing: reference/config/graph_indexing.md
+          - fusion: reference/config/fusion.md
+          - vector_search: reference/config/vector_search.md
+          - sparse_search: reference/config/sparse_search.md
+          - graph_search: reference/config/graph_search.md
+          - reranking: reference/config/reranking.md
+          - generation: reference/config/generation.md
+          - enrichment: reference/config/enrichment.md
+          - chunk_summaries: reference/config/chunk_summaries.md
+          - keywords: reference/config/keywords.md
+          - tracing: reference/config/tracing.md
+          - training: reference/config/training.md
+          - ui: reference/config/ui.md
+          - chat: reference/config/chat.md
+          - hydration: reference/config/hydration.md
+          - evaluation: reference/config/evaluation.md
+          - system_prompts: reference/config/system_prompts.md
+          - mcp: reference/config/mcp.md
+          - docker: reference/config/docker.md
       - API: api.md
       - Models: models.md
       - Glossary: glossary.md

mkdocs/docs/configuration.md

@@ -24,6 +24,7 @@
 
 [Get started](index.md){ .md-button .md-button--primary }
 [Configuration](configuration.md){ .md-button }
+[Config reference](reference/config/index.md){ .md-button }
 [API](api.md){ .md-button }
 
 !!! tip "Workflow: Pydantic First"
@@ -50,6 +51,13 @@ flowchart TB
 
 ## Major Sections (Selected Fields)
 
+!!! tip "Need the full 1000+ parameter surface?"
+    Use the auto-generated [Configuration Reference](reference/config/index.md) pages. They enumerate **every** tunable key with:
+    - JSON path (`retrieval.rrf_k_div`)
+    - env-style key (when available, via `TriBridConfig.to_flat_dict()`)
+    - type, default, and validation constraints
+    - long-form “tooltip” guidance pulled from `data/glossary.json` (when present)
+
 | Section | Key Fields (examples) | Why it matters |
 |--------|------------------------|----------------|
 | retrieval | `final_k`, `topk_dense`, `topk_sparse`, `fallback_confidence`, `conf_top1`, `conf_avg5`, `multi_query_m` | Controls candidate sizes and retry/accept gates |

mkdocs/docs/dev/docs-autopilot.md

@@ -36,6 +36,7 @@ There are two GitHub Actions workflows:
   - Builds a **plan artifact** from `git diff`
   - Calls the LLM to generate a **unified diff patch**
   - Applies + commits doc updates back to the branch
+  - Regenerates the **full config reference** from Pydantic + glossary
   - Verifies `mkdocs build --strict`
 
 - `Publish MkDocs (mike)`:
@@ -67,6 +68,7 @@ Generate + apply patch (requires `OPENAI_API_KEY`):
 ```bash
 export OPENAI_API_KEY=...
 python scripts/docs_ai/generate_docs_from_diff.py --base origin/main --llm openai --apply
+uv run python scripts/generate_config_reference_docs.py --clean
 mkdocs build --strict
 ```
 

mkdocs/docs/index.md

@@ -1,4 +1,4 @@
-# TriBridRAG Documentation
+# ragweld Documentation
 
 <div class="grid chunk_summaries" markdown>
 
@@ -42,8 +42,12 @@
 
 [Get started](index.md){ .md-button .md-button--primary }
 [Configuration](configuration.md){ .md-button }
+[Config reference](reference/config/index.md){ .md-button }
 [API](api.md){ .md-button }
 
+!!! note "Naming: ragweld vs tribrid"
+    The repo/product is **ragweld**. Many internal names still say **tribrid** (config keys, module names, older docs). Treat `tribrid` as stable internal naming; don’t mass-rename it.
+
 !!! tip "Read This First"
     TriBridRAG is strictly Pydantic-first. If a field or feature is not in `server/models/tribrid_config_model.py`, it does not exist. Add it there, regenerate TypeScript types, then build the rest.
 

mkdocs/docs/manual/native_postgres.md

@@ -9,7 +9,7 @@ This repo supports that workflow via:
 ```
 
 !!! important "Compatibility"
-    `--native-postgres` is supported only with the **local backend** (uvicorn) and **without** `--with-observability`.
+    `--native-postgres` works with the local backend and with the Docker backend/observability stack. When Docker is involved, containers connect to your host Postgres via `host.docker.internal`.
 
 ## 1) Stop Docker Postgres (if it’s running)