skills.rest
kreuzberg-dev
kreuzberg-devOFFICIAL
Explore all skills by this author →
WebsiteGitHub

config-loading-precedence

Explains Xberg configuration precedence, auto-discovery, and silent no-op failure modes.

9.2k|581|Updated Jan 31, 2025
Search Tags:#Configuration#TOML#Debugging#serde#precedence#config discovery#CLI flags
One-click install
npx skills add https://github.com/kreuzberg-dev/kreuzberg --skill config-loading-precedence
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: config-loading-precedence
Source: https://github.com/kreuzberg-dev/kreuzberg/tree/main/.ai-rulez/skills/config-loading-precedence
Command: npx skills add https://github.com/kreuzberg-dev/kreuzberg --skill config-loading-precedence

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Configuration changes in Xberg can silently do nothing due to duplicate Default impls, ignored unknown keys, and misunderstood precedence rules, making debugging config behavior frustrating and error-prone.

Core Features & Use Cases

  • Precedence Reference: Documents the exact precedence order for CLI mode (flags > inline JSON > config file > auto-discovery > defaults) and server/MCP mode (CLI args > env vars > [server] section > defaults).
  • Discovery Rules: Clarifies that auto-discovery walks parent directories for xberg.toml only, while YAML/JSON configs require an explicit --config flag.
  • Silent Failure Diagnosis: Identifies the two mechanisms that make config changes no-ops: duplicate TesseractConfig Default impls and serde silently ignoring unknown keys in nested configs.
  • Use Case: When adding a new config flag or debugging why a setting in xberg.toml is not taking effect, consult this Skill to trace which precedence layer wins and whether a typo'd key is being silently dropped.

Quick Start

Ask the AI to explain why my xberg.toml setting for chunking max_chars is not taking effect and which precedence layer is overriding it.

Frequently Asked Questions about config-loading-precedence

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I override Xberg config file settings from the CLI?▼

Individual CLI flags like --ocr, --output-format, and --chunk have the highest precedence and override everything else. Below them come inline JSON via --config-json, then an explicit --config file, then auto-discovered config, then defaults.

Why is my xberg.yaml config file not being loaded automatically?▼

Auto-discovery only walks the current directory and parents looking for xberg.toml, not .yaml, .yml, or .json files. A project-local xberg.yaml must be passed explicitly with the --config flag.

Why does my config change silently do nothing in Xberg?▼

Two common causes: duplicate Default impls exist for types like TesseractConfig, so changing one default only affects some code paths, and nested config structs silently ignore unknown keys, so a typo'd key parses cleanly but does nothing.

Does inline JSON config replace the whole Xberg config object?▼

No, inline JSON via --config-json or --config-json-base64 performs a field-level merge into the existing config, not whole-object replacement. Use --config-json-base64 to avoid shell escaping issues.

What is the config precedence for Xberg server and MCP mode?▼

Server mode precedence is CLI arguments like --host and --port first, then environment variables XBERG_HOST and XBERG_PORT, then the config file [server] section, and finally defaults of 127.0.0.1:8000.

Related Skills

Explore More Software Engineering Skills→
starlake-aistarlake-ai
1

config

Validate Starlake YAML configuration files against the Starlake JSON Schema.

Official
Advanced
redhat-documentationredhat-documentation

jtbd-analyze-adoc

Extract JTBD records from Red Hat modular AsciiDoc documentation.

Official
Advanced
Arm-ExamplesArm-Examples
4

llm-config-schema-change

Modify LLM configuration schemas by updating parsing logic, tests, and documentation for JSON config keys.

Official
Intermediate
tharunramagiritharunramagiri

use-native-credential-proxy

Inject Anthropic credentials from .env files into container environments.

Community
Intermediate