config

Config Loader

Loads, manages, and merges YAML configuration files for Obsidian vault management with support for vault-specific overrides.

Slash Commands (v1.0.0)

Command	Description
obsidian:config	Show current vault configuration
obsidian:config show	Show detailed configuration (with --verbose)
obsidian:config edit	Edit settings in system editor
obsidian:config validate	Validate configuration structure
obsidian:config methodologies	List available methodologies
obsidian:config create --methodology para	Create default settings
obsidian:config diff	Show difference from defaults

Architecture

This skill provides three complementary modules:

settings_loader.py (PRIMARY - Source of Truth)

• Loads .claude/settings.yaml as the primary configuration source
• All validation rules come from here
• Generated by init-skill or custom wizard
• Use for: validation, note type checking, UP links

config_loader.py (UTILITY - YAML Management)

• Loads and merges additional YAML config files
• Provides fallback defaults when settings.yaml doesn't exist
• Use for: config file merging, custom YAML management

methodology loader (config/methodologies/loader.py)

• Loads methodology definitions from YAML files
• Provides METHODOLOGIES proxy for dict-like access
• Used by init_vault.py to create vaults
• Use for: methodology listing, vault initialization

Quick Start

# Load user settings (PRIMARY - use this for validation)
uv run scripts/settings_loader.py --vault /path/to/vault --show --validate

# Load YAML config files (UTILITY)
uv run scripts/config_loader.py --vault /path/to/vault --show

# Create default settings if missing
uv run scripts/settings_loader.py --vault /path/to/vault --create --show

Features

• Unified Settings: Single .claude/settings.yaml as source of truth
• Methodology Support: LYT-ACE, PARA, Zettelkasten, Minimal, Custom
• Type-Safe Operations: Full type hints with dataclasses
• Note Type Inference: Automatically infer types from folder paths
• UP Link Resolution: Get expected parent MOC for any file
• Exclusion Handling: Inbox and system files properly excluded
• JSONL Logging: Audit trail support for validation operations

Configuration Hierarchy

The config loader merges configurations in this order (later overrides earlier):

1. DEFAULT_CONFIG (embedded in script)
2. Skill defaults (skills/config/config/{name}.yaml)
3. Vault overrides (.claude/config/{name}.yaml in vault)

Usage Examples

Load Settings (PRIMARY - Recommended)

from pathlib import Path
from settings_loader import load_settings, get_note_type, get_validation_rules

# Load settings (creates default if create_if_missing=True)
settings = load_settings(Path("/path/to/vault"), create_if_missing=True)

# Get note type configuration
map_type = get_note_type(settings, "map")
print(map_type.description)       # "Map of Content - Overview and navigation notes"
print(map_type.required_properties)  # ["type", "up", "created", ...]

# Get validation rules
rules = get_validation_rules(settings)
print(rules.require_core_properties)  # True
print(rules.allow_empty_properties)   # ["tags", "collection", "related"]

Infer Note Type and UP Link

from pathlib import Path
from settings_loader import (
    load_settings,
    infer_note_type_from_path,
    get_up_link_for_path,
    should_exclude,
)

settings = load_settings(Path("/vault"))
file_path = Path("/vault/Atlas/Dots/Concept.md")

# Infer note type
note_type = infer_note_type_from_path(settings, file_path)
print(note_type)  # "dot"

# Get expected UP link
up_link = get_up_link_for_path(settings, file_path)
print(up_link)  # "[[Atlas/Maps/Dots]]"

# Check if excluded from validation
inbox_file = Path("/vault/+/new_idea.md")
print(should_exclude(settings, inbox_file))  # True

Load YAML Configuration (UTILITY)

from pathlib import Path
from config_loader import load_config

# Load default configuration
config = load_config(Path("/path/to/vault"))

# Load custom configuration
config = load_config(Path("/path/to/vault"), "custom.yaml")

Save Custom Configuration

from pathlib import Path
from config_loader import save_config

custom_config = {
    "core_properties": ["type", "up", "created", "daily", "tags", "collection", "related"],
    "note_types": {
        "custom": {
            "description": "Custom note type",
            "properties": ["type", "up", "created", "daily", "tags", "collection", "related"]
        }
    }
}

save_config(Path("/path/to/vault"), custom_config, "custom.yaml")

Merge Configurations

from config_loader import merge_configs

base = {
    "core_properties": ["type", "up"],
    "validation": {"strict": true}
}

override = {
    "core_properties": ["type", "up", "created"],
    "auto_fix": {"enabled": true}
}

merged = merge_configs(base, override)
# Result: All keys from both, override takes precedence for conflicts

Get Note Type Configuration

from config_loader import load_config, get_note_type_config

config = load_config(Path("/path/to/vault"))
map_config = get_note_type_config(config, "map")

print(map_config["description"])  # "Map of Content - Overview and navigation notes"
print(map_config["properties"])   # ["type", "up", "created", "daily", ...]

Infer Note Type from Path

from pathlib import Path
from config_loader import load_config, infer_note_type

config = load_config(Path("/vault"))
file_path = Path("/vault/Atlas/Maps/My Map.md")

note_type = infer_note_type(file_path, config)
print(note_type)  # "map"

Validate Configuration

from config_loader import load_config, validate_config

config = load_config(Path("/path/to/vault"))
errors = validate_config(config)

if errors:
    for error in errors:
        print(f"Error: {error}")
else:
    print("Configuration is valid")

Configuration Files

default.yaml

Core configuration with:

• core_properties: Required frontmatter properties for all notes
• note_types: Note type definitions with folder hints and properties
• validation: Validation rules
• auto_fix: Auto-fix toggles
• exclude_paths: Paths to exclude from processing
• exclude_files: Files to exclude from processing

frontmatter-defaults.yaml

Default frontmatter templates for:

• New notes (minimal template)
• Each note type (map, dot, source, project, area, daily, effort)
• Date formats and link formats
• Default parent links by note type

note-types-defaults.yaml

Extended note type configuration with:

• Detailed descriptions and aliases
• Icon assignments
• Required vs optional properties
• Type-specific validation rules
• Property type definitions with data types

Note Types

The default configuration includes these note types:

Type	Description	Folder Hints
map	Map of Content - Overview and navigation notes	Atlas/Maps/, Maps/
dot	Dot notes - Atomic concepts and ideas	Atlas/Dots/, Dots/
source	Source notes - External references	Atlas/Sources/, Sources/
effort	Effort notes - Work and tasks	Efforts/
project	Project notes - Defined outcomes	Efforts/Projects/, Projects/
area	Area notes - Ongoing responsibilities	Efforts/Areas/, Areas/
daily	Daily notes - Date-based journal entries	Calendar/daily/, daily/

Core Properties

All notes require these 7 properties (per vault standards):

type: dot           # Note type
up: "[[Parent]]"    # Parent note link (quoted)
created: 2025-01-15 # Creation date (YYYY-MM-DD)
daily: "[[2025-01-15]]"  # Daily note link (quoted)
tags:               # Tags for categorization (can be empty)
collection:         # Collection classification (can be empty)
related:            # Related notes (can be empty)

Vault-Specific Overrides

To customize configuration for a specific vault:

1. Create .claude/config/ directory in vault root
2. Add YAML file (e.g., custom.yaml)
3. Define only the properties you want to override

Example .claude/config/custom.yaml:

# Override just the note types
note_types:
  blog:
    description: "Blog post notes"
    folder_hints:
      - "Blog/"
    properties:
      - type
      - up
      - created
      - daily
      - published
      - tags

# Keep all other defaults from skill config

API Reference

load_config(vault_path, config_name)

Load configuration with hierarchical merging.

Parameters:

• vault_path (Path): Path to Obsidian vault root
• config_name (str): Config file name (default: "default.yaml")

Returns: dict[str, Any] - Merged configuration

Raises:

• ValueError: If vault path invalid
• yaml.YAMLError: If YAML parsing fails

save_config(vault_path, config, config_name)

Save configuration to vault-specific location.

Parameters:

• vault_path (Path): Path to vault root
• config (dict): Configuration to save
• config_name (str): Config file name (default: "custom.yaml")

Raises:

• ValueError: If vault path invalid
• OSError: If file cannot be written

merge_configs(base, override)

Deep merge two configuration dictionaries.

Parameters:

• base (dict): Base configuration
• override (dict): Override configuration

Returns: dict[str, Any] - Merged configuration

get_note_type_config(config, note_type)

Get configuration for specific note type.

Parameters:

• config (dict): Configuration dictionary
• note_type (str): Note type identifier

Returns: dict[str, Any] | None - Note type config or None

infer_note_type(file_path, config)

Infer note type from file path using folder hints.

Parameters:

• file_path (Path): Path to markdown file
• config (dict): Configuration dictionary

Returns: str | None - Inferred note type or None

validate_config(config)

Validate configuration structure.

Parameters:

• config (dict): Configuration to validate

Returns: list[str] - Validation errors (empty if valid)

Integration with Claude Code

When user requests configuration management:

1. Determine vault path (usually current directory or user-specified)
2. Load configuration with appropriate hierarchy
3. Perform requested operation (load, save, merge, validate)
4. Report results and configuration details

Exit Codes

• 0: Success
• 1: Error (invalid vault, YAML error, validation failed)

Dependencies

• Python 3.10+
• PyYAML >= 6.0 (via PEP 723 inline dependencies)

When to Use Each Module

Need validation rules, note types, UP links?
  → settings_loader.py (PRIMARY)

Need to merge YAML config files?
  → config_loader.py (UTILITY)

Need methodology definitions for vault init?
  → methodology loader (config/methodologies/loader.py)

Recommended entry point: Always start with settings_loader.py unless you specifically need YAML file merging.

Interactive Mode

Terminal

In terminal mode, the interactive wizard guides you through configuration options.

Claude Code / Non-Interactive

When called without a terminal (e.g., in Claude Code), JSON is returned:

{
  "interactive_required": true,
  "action": "edit",
  "config_schema": {...}
}

Use --config='...' or --yes to pass values directly.