# Configuration Management

[← Developer Experience](Developer-Experience.md) | [Home](Home.md) | [Alias Management →](Alias-Management.md)

---

## Table of Contents

- [Overview](#overview)
- [v3.1.0 File-Based Workflow](#v31-file-based-workflow)
- [File Structure and Naming](#file-structure-and-naming)
- [Load Order Control](#load-order-control)
- [Creating Config Files](#creating-config-files)
- [File Format](#file-format)
- [Managing Configs](#managing-configs)
- [Common Config Patterns](#common-config-patterns)
- [Load Order Examples](#load-order-examples)
- [Security Considerations](#security-considerations)
- [Migration from v2.x](#migration-from-v2x)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)
- [Next Steps](#next-steps)

## Overview

DotRun v3.1.0 uses a simple, file-based configuration system using plain Bash exports. Configuration files are automatically sourced at shell startup, providing a clean and maintainable way to manage environment variables, PATH configuration, API keys, and development tool settings.

**Key Features**:

- **File-based**: Config files in `~/.config/dotrun/configs/`
- **Auto-loaded**: Sourced automatically via `~/.drrc` at shell startup
- **Load order**: NN-category naming controls load sequence
- **Simple syntax**: Plain Bash `export` statements only
- **Category-based**: Organize by purpose (paths, api, development, cloud)

**Critical**: PATH must be configured first (in `01-paths.config`) before any other configs that depend on it.

## v3.1.0 File-Based Workflow

Configuration in DotRun v3.1.0 works as follows:

1. **At shell startup**: `~/.drrc` sources every `*.config` file in `~/.config/dotrun/configs/`
2. **Load order**: Files are loaded in lexicographic order (01, 02, 03, ... 10, 11, ...)
3. **Plain Bash**: Each file contains simple `export` statements
4. **Categories**: Organize by topic (paths, api, development, cloud, local)
5. **PATH baseline**: Established in `01-paths.config` before everything else

This approach replaces any hypothetical v2.x command-driven or YAML/JSON config systems with a straightforward, maintainable pattern.

## File Structure and Naming

**Directory**: `~/.config/dotrun/configs/`

**Naming Convention**: `NN-category.config`

- **NN**: Two-digit number (01-99) controlling load order
- **category**: Descriptive name (lowercase, hyphens allowed)
- **extension**: `.config`

**Example Structure**:

```
~/.config/dotrun/configs/
├── 01-paths.config          # PATH configuration (MUST load first)
├── 02-xdg.config            # XDG base directories
├── 05-api.config            # API keys and tokens
├── 10-development.config    # Development tools
├── 20-cloud.config          # Cloud provider configs
└── 90-local.config          # Machine-specific overrides
```

**Numbering Guidelines**:

- **00-09**: Core/baseline (paths, XDG)
- **10-49**: Development tools and languages
- **50-79**: Services and middleware
- **80-89**: Team/project overrides
- **90-99**: Local machine-specific overrides

## Load Order Control

Files are sourced in **lexicographic order** by filename. The numeric prefix enforces the sequence.

**Why Order Matters**:

1. **PATH Dependencies**: Tools and scripts depend on PATH being set correctly
2. **Variable References**: Later configs can reference variables from earlier configs
3. **Intentional Overrides**: Later files can override earlier exports

**Critical Rule**: All PATH setup must happen in `01-paths.config` before any other config that:

- Appends to PATH
- Executes commands found via PATH
- Loads tools that modify PATH (nvm, pyenv, etc.)

**Numbering Strategy**:

```bash
# Good: Clear ordering with room for additions
01-paths.config       # Baseline PATH
02-xdg.config         # XDG directories
05-api.config         # API keys
10-development.config # Dev tools
15-languages.config   # Language-specific (if needed later)
20-cloud.config       # Cloud providers
90-local.config       # Local overrides

# Bad: No room for additions
1-paths.config
2-xdg.config
3-api.config
# What happens when you need something between 1 and 2?
```

## Creating Config Files

DotRun v3.1.0 has no command interface for config management. Create and edit files manually.

**Step 1: Ensure Directory Exists**

```bash
mkdir -p ~/.config/dotrun/configs
```

**Step 2: Create Config File**

```bash
# Use your preferred editor
$EDITOR ~/.config/dotrun/configs/01-paths.config

# Or directly
vim ~/.config/dotrun/configs/05-api.config
```

**Step 3: Reload Shell**

```bash
# Option 1: Reload in current shell
source ~/.drrc

# Option 2: Start new shell (cleaner)
exec $SHELL
```

**Step 4: Verify**

```bash
# Check specific variable
echo "$EDITOR"

# Check PATH
echo "$PATH"

# Check all environment variables
env | grep -E '^(GITHUB_TOKEN|AWS_|EDITOR|GOPATH)'
```

**Shell Integration Check**:

If configs aren't loading, ensure `~/.drrc` is sourced in your shell's RC file:

```bash
# Add to ~/.bashrc or ~/.zshrc
[ -f "$HOME/.drrc" ] && . "$HOME/.drrc"
```

## File Format

Config files use plain Bash syntax with `export` statements.

**Basic Export**:

```bash
export EDITOR="vim"
export VISUAL="$EDITOR"
```

**PATH Operations**:

```bash
# Prepend to PATH
export PATH="$HOME/.local/bin:$PATH"

# Append to PATH
export PATH="$PATH:$HOME/tools/bin"

# Set PATH from scratch (only in 01-paths.config!)
export PATH="/usr/local/bin:/usr/bin:/bin"
```

**Quoted Values** (for safety):

```bash
# Always quote values with spaces or special characters
export PROJECT_NAME="My Awesome Project"
export DATABASE_URL="postgresql://user:pass@localhost/db"
```

**Optional Guarded Sourcing**:

```bash
# Load external scripts if they exist
[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"
```

**Best Practices**:

- Always use `export` for variables visible to child processes
- Quote all string values
- Keep commands minimal; prefer straight exports
- Add comments explaining non-obvious choices

## Managing Configs

**Listing Configs**:

```bash
# View all config files in load order
ls -1 ~/.config/dotrun/configs

# Or with details
ls -lh ~/.config/dotrun/configs/*.config
```

**Editing Configs**:

```bash
# Edit specific file
$EDITOR ~/.config/dotrun/configs/10-development.config

# Edit with vim
vim ~/.config/dotrun/configs/05-api.config
```

**Reloading Configs**:

```bash
# Reload in current shell
source ~/.drrc

# Or start fresh shell (preferred)
exec $SHELL
```

**Validating Configs**:

```bash
# Check syntax without executing
bash -n ~/.config/dotrun/configs/10-development.config

# View PATH line-by-line
printf "%s\n" "${PATH//:/$'\n'}"

# Search for specific exports
grep -R "export GITHUB_TOKEN" ~/.config/dotrun/configs
```

**Removing Configs**:

```bash
# Delete file
rm ~/.config/dotrun/configs/20-cloud.config

# Or rename to disable without deleting
mv ~/.config/dotrun/configs/05-api.config{,.disabled}
```

## Common Config Patterns

### 1. PATH Configuration (01-paths.config)

**Purpose**: Establish baseline PATH that works across platforms. MUST load first.

```bash
# ~/.config/dotrun/configs/01-paths.config
# PATH Configuration - MUST LOAD FIRST
# Last Updated: 2024-01-15

# System baseline
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

# User-level binaries (highest priority)
export PATH="$HOME/.local/bin:$PATH"

# Language-specific paths
export PATH="$HOME/.cargo/bin:$PATH"      # Rust
export PATH="$HOME/go/bin:$PATH"          # Go
export PATH="$HOME/.npm-global/bin:$PATH" # npm global

# Homebrew (macOS)
# Intel Macs
export PATH="/usr/local/bin:$PATH"
# Apple Silicon Macs
export PATH="/opt/homebrew/bin:$PATH"

# Project-local binaries
export PATH="./node_modules/.bin:$PATH"

# Snap packages (Linux)
export PATH="/snap/bin:$PATH"
```

### 2. XDG Directories (02-xdg.config)

**Purpose**: Normalize XDG base directories for cleaner home directory.

```bash
# ~/.config/dotrun/configs/02-xdg.config
# XDG Base Directory Specification
# Ensures consistent locations for config, cache, and data

export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_CACHE_HOME="$HOME/.cache"
export XDG_STATE_HOME="$HOME/.local/state"

# Optional: Configure tools to use XDG paths
export LESSHISTFILE="$XDG_STATE_HOME/less/history"
export DOCKER_CONFIG="$XDG_CONFIG_HOME/docker"
export NPM_CONFIG_USERCONFIG="$XDG_CONFIG_HOME/npm/npmrc"
```

### 3. API Keys (05-api.config)

**Purpose**: Central location for API tokens and service credentials.

**⚠️ SECURITY WARNING**: This file contains plain text secrets. Never commit to git!

```bash
# ~/.config/dotrun/configs/05-api.config
# API Keys and Tokens (SENSITIVE - DO NOT COMMIT)
# File permissions: chmod 600 05-api.config

# GitHub
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# OpenAI
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# AWS (use aws-vault or similar for production)
export AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export AWS_DEFAULT_REGION="us-east-1"

# Sentry
export SENTRY_AUTH_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# npm
export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Database (development only!)
export DATABASE_URL="postgresql://user:password@localhost:5432/myapp_dev"

# Note: Consider using secrets management tools instead:
# - 1Password CLI: op read "op://vault/item/field"
# - AWS Secrets Manager: aws secretsmanager get-secret-value
# - HashiCorp Vault: vault kv get secret/path
```

### 4. Development Tools (10-development.config)

**Purpose**: Development environment settings and tool configuration.

```bash
# ~/.config/dotrun/configs/10-development.config
# Development Tools and Preferences

# Editor and pager
export EDITOR="vim"
export VISUAL="code --wait"
export PAGER="less -RFX"

# Go
export GOPATH="$HOME/go"
export GOBIN="$GOPATH/bin"
export GO111MODULE="on"

# Node.js (pnpm example)
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# Python
export PIPX_HOME="$HOME/.local/pipx"
export PIPX_BIN_DIR="$HOME/.local/bin"
export PYTHONUNBUFFERED=1

# Ruby
export GEM_HOME="$HOME/.gem"
export PATH="$GEM_HOME/bin:$PATH"

# Rust
export CARGO_HOME="$HOME/.cargo"
export RUSTUP_HOME="$HOME/.rustup"

# Build tools
export MAKEFLAGS="-j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)"

# Development mode
export NODE_ENV="development"
export RUST_BACKTRACE="1"
export PYTHONDONTWRITEBYTECODE=1

# Optional: Load version managers
[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"
```

### 5. Cloud Providers (20-cloud.config)

**Purpose**: Cloud provider configuration and preferences.

```bash
# ~/.config/dotrun/configs/20-cloud.config
# Cloud Provider Configuration

# AWS
export AWS_PROFILE="default"
export AWS_DEFAULT_REGION="us-east-1"
export AWS_DEFAULT_OUTPUT="json"
export AWS_CONFIG_FILE="$HOME/.aws/config"
export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/credentials"

# Google Cloud Platform
export CLOUDSDK_CONFIG="$HOME/.config/gcloud"
export CLOUDSDK_CORE_PROJECT="my-project"
export CLOUDSDK_COMPUTE_REGION="us-central1"
export CLOUDSDK_COMPUTE_ZONE="us-central1-a"

# Azure
export AZURE_CONFIG_DIR="$HOME/.azure"

# Terraform
export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
# export TF_VAR_environment="development"

# Kubernetes
export KUBECONFIG="$HOME/.kube/config"

# Docker
export DOCKER_CONFIG="$XDG_CONFIG_HOME/docker"
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
```

### 6. Local Overrides (90-local.config)

**Purpose**: Machine-specific overrides that load last. Never commit this file.

```bash
# ~/.config/dotrun/configs/90-local.config
# Machine-Specific Overrides (DO NOT COMMIT)
# Loads last to override previous settings

# Corporate proxy (if needed)
# export HTTP_PROXY="http://proxy.company.com:8080"
# export HTTPS_PROXY="$HTTP_PROXY"
# export NO_PROXY="localhost,127.0.0.1,.company.com"

# Machine-specific PATH additions
# export PATH="/opt/company-tools/bin:$PATH"

# Override editor on work laptop
# export EDITOR="code --wait"
# export VISUAL="$EDITOR"

# Local API endpoint for development
# export API_BASE_URL="http://localhost:3000"

# Override AWS profile for this machine
# export AWS_PROFILE="personal"

# macOS Apple Silicon specific
# export PATH="/opt/homebrew/bin:$PATH"

# Local database connection
# export DATABASE_URL="postgresql://localhost/myapp_local"
```

## Load Order Examples

### ✅ Good: PATH First, Dependencies Later

```
01-paths.config          # Sets PATH baseline
02-xdg.config            # XDG directories
05-api.config            # API keys
10-development.config    # Adds Go/Node/Python to PATH
20-cloud.config          # Uses cloud CLIs from PATH
90-local.config          # Local overrides
```

**Why it works**:

- PATH is ready before any tools try to use it
- Development configs can safely append to PATH
- Cloud configs can execute tools found via PATH
- Local overrides take precedence over earlier settings

### ❌ Bad: Tools Before PATH

```
10-development.config    # Tries to use tools
01-paths.config          # Sets PATH too late!
20-cloud.config
```

**What breaks**:

- Development config tries to run `go` or `node` before PATH is set
- Tools may not be found or wrong versions execute
- PATH modifications happen in wrong order
- `command -v` checks fail unexpectedly

### ❌ Bad: Sourcing Before PATH Baseline

```
05-api.config
10-development.config    # Contains: [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
01-paths.config          # Sets PATH last
```

**What breaks**:

- `nvm.sh` sourcing can fail if it expects PATH to be configured
- NVM_DIR may not be set or may point to wrong location
- Tools added by nvm won't be found in correct order
- Inconsistent behavior across different terminal sessions

## Security Considerations

Configuration files may contain sensitive information. Follow these security practices.

### File Permissions

Restrict access to sensitive config files:

```bash
# Lock down entire configs directory
chmod 700 ~/.config/dotrun
chmod 700 ~/.config/dotrun/configs

# Sensitive files should be user-readable only
chmod 600 ~/.config/dotrun/configs/05-api.config
chmod 600 ~/.config/dotrun/configs/90-local.config
```

### Version Control

**Never commit secrets to git**:

```bash
# Add to .gitignore
~/.config/dotrun/configs/05-api.config
~/.config/dotrun/configs/90-local.config
~/.config/dotrun/configs/*local.config
~/.config/dotrun/configs/*secrets.config
```

### Secrets Management Alternatives

Instead of plain text secrets, use secure alternatives:

**1Password CLI**:

```bash
# Store in 1Password, retrieve at runtime
export GITHUB_TOKEN="$(op read 'op://Personal/GitHub/token')"
export AWS_SECRET_ACCESS_KEY="$(op read 'op://Work/AWS/secret_key')"
```

**macOS Keychain**:

```bash
# Store once
security add-generic-password -a "$USER" -s "github-token" -w "ghp_xxxxx"

# Retrieve in config
export GITHUB_TOKEN="$(security find-generic-password -a "$USER" -s "github-token" -w)"
```

**Linux Secret Service**:

```bash
# Store once
secret-tool store --label="GitHub Token" service dotrun username github

# Retrieve in config
export GITHUB_TOKEN="$(secret-tool lookup service dotrun username github)"
```

**AWS Secrets Manager**:

```bash
# Retrieve from AWS
export DATABASE_PASSWORD="$(aws secretsmanager get-secret-value \
  --secret-id prod/db/password \
  --query SecretString \
  --output text)"
```

**HashiCorp Vault**:

```bash
# Retrieve from Vault
export API_KEY="$(vault kv get -field=key secret/api/production)"
```

### Best Practices

1. **Minimal Secrets**: Only store secrets you absolutely need in config files
2. **Scoped Tokens**: Use tokens with minimal permissions
3. **Rotation**: Rotate credentials regularly
4. **Avoid Logging**: Never echo secret values to logs
5. **Disable Debug**: Avoid `set -x` when sourcing configs (prints all variables)
6. **Separate Files**: Keep secrets in separate files (05-api.config, 90-local.config)
7. **Audit**: Regularly review who has access to config files

### Security Checklist

```bash
# ✅ File permissions locked down
ls -la ~/.config/dotrun/configs/*.config | grep "^-rw-------"

# ✅ Secrets not in git
git status ~/.config/dotrun/configs/

# ✅ No world-readable files
find ~/.config/dotrun -type f -perm -004

# ✅ No secrets in shell history
grep -i "export.*token\|export.*key\|export.*password" ~/.bash_history
```

## Migration from v2.x

If you're migrating from a hypothetical v2.x system with command-driven configs or YAML/JSON patterns:

### What Changed

**v2.x** (hypothetical):

- Command-driven: `dr config set KEY value`
- Complex formats: YAML/JSON configs
- Special variables: `DR_HOME`, `DR_BIN`, `DR_DOCS`
- Tool-managed: Configs stored in database or single file

**v3.1.0** (actual):

- File-based: Manual `.config` files
- Simple format: Plain Bash `export` statements
- Standard paths: `~/.config/dotrun/configs/`
- User-managed: Direct file editing

### Migration Steps

**Step 1: Disable v2.x Hooks**

```bash
# Edit shell RC files
vim ~/.bashrc # or ~/.zshrc

# Comment out or remove v2.x-specific lines
# OLD: source ~/.dotrun/env
# OLD: eval "$(dr config load)"
```

**Step 2: Create v3.1.0 Files**

```bash
# Create directory
mkdir -p ~/.config/dotrun/configs

# Create core files
touch ~/.config/dotrun/configs/01-paths.config
touch ~/.config/dotrun/configs/02-xdg.config
touch ~/.config/dotrun/configs/05-api.config
touch ~/.config/dotrun/configs/10-development.config
touch ~/.config/dotrun/configs/20-cloud.config
touch ~/.config/dotrun/configs/90-local.config
```

**Step 3: Translate Variables**

```bash
# OLD v2.x (hypothetical)
dr config set EDITOR vim
dr config set API_KEY sk-xxxxx
dr config set GOPATH ~/go

# NEW v3.1.0 (in 10-development.config)
export EDITOR="vim"
export GOPATH="$HOME/go"

# NEW v3.1.0 (in 05-api.config)
export API_KEY="sk-xxxxx"
```

**Step 4: Set PATH Explicitly**

```bash
# OLD v2.x: May have managed PATH automatically
# NEW v3.1.0: Explicit in 01-paths.config

# ~/.config/dotrun/configs/01-paths.config
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$HOME/go/bin:$PATH"
```

**Step 5: Test and Validate**

```bash
# Reload configs
source ~/.drrc

# Verify variables
echo "$EDITOR"
echo "$GOPATH"
env | grep -E '^(API_KEY|GITHUB_TOKEN|AWS_)'

# Verify PATH
printf "%s\n" "${PATH//:/$'\n'}"

# Test in new shell
exec $SHELL
```

**Step 6: Clean Up**

```bash
# Remove obsolete v2.x files
rm -rf ~/.dotrun/               # If this was v2.x location
rm ~/.config/dotrun/config.yml  # If YAML configs existed
rm ~/.config/dotrun/config.json # If JSON configs existed

# Clean shell history (optional)
history -c
```

### Variable Translation Table

| v2.x Variable  | v3.1.0 Approach                                 |
| -------------- | ----------------------------------------------- |
| `DR_HOME`      | Not used; use `~/.config/dotrun` directly       |
| `DR_BIN`       | Not used; scripts in `~/.config/dotrun/scripts` |
| `DR_DOCS`      | Not used                                        |
| Custom configs | Export in appropriate `.config` file            |
| Secrets        | Store in `05-api.config` or use secrets manager |

## Best Practices

### 1. PATH First Always

```bash
# ✅ GOOD: PATH in 01-paths.config
# ~/.config/dotrun/configs/01-paths.config
export PATH="$HOME/.local/bin:$PATH"

# ❌ BAD: PATH in 10-development.config
# Wrong numeric prefix - tools may fail before this loads
```

### 2. Keep It Simple

```bash
# ✅ GOOD: Direct exports
export EDITOR="vim"
export GOPATH="$HOME/go"

# ❌ BAD: Complex logic
if [ -x "$(command -v code)" ]; then
  export EDITOR="$(which code) --wait"
elif [ -x "$(command -v vim)" ]; then
  export EDITOR="vim"
else
  export EDITOR="nano"
fi
# This belongs in a script, not a config file
```

### 3. Focused Categories

```bash
# ✅ GOOD: Many focused files
01-paths.config       # Only PATH
02-xdg.config         # Only XDG
05-api.config         # Only secrets
10-development.config # Only dev tools

# ❌ BAD: One huge file
00-everything.config # 500 lines of mixed concerns
```

### 4. Separate Secrets

```bash
# ✅ GOOD: Secrets isolated
05-api.config   # All secrets here
90-local.config # Machine-specific secrets
# Both excluded from git

# ❌ BAD: Secrets scattered
10-development.config # export GITHUB_TOKEN="..."
20-cloud.config       # export AWS_SECRET_KEY="..."
# Hard to manage, easy to accidentally commit
```

### 5. Use Absolute Paths

```bash
# ✅ GOOD: Absolute with $HOME
export GOPATH="$HOME/go"
export CARGO_HOME="$HOME/.cargo"

# ❌ BAD: Relative or tilde in exports
export GOPATH="~/go"          # Tilde may not expand correctly
export CARGO_HOME="../.cargo" # Relative paths break
```

### 6. Idempotent Sourcing

```bash
# ✅ GOOD: Safe to source multiple times
export PATH="$HOME/.local/bin:$PATH"
# Each re-source just prepends again (mostly harmless)

# ✅ BETTER: Check before adding to PATH (advanced)
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
  export PATH="$HOME/.local/bin:$PATH"
fi

# Note: Generally prefer opening new shell over re-sourcing
```

### 7. Validate Frequently

```bash
# Check syntax before sourcing
bash -n ~/.config/dotrun/configs/10-development.config

# View PATH clearly
printf "%s\n" "${PATH//:/$'\n'}"

# Search for duplicates
grep -R "export EDITOR" ~/.config/dotrun/configs
```

### 8. Document Choices

```bash
# ✅ GOOD: Commented and explained
# ~/.config/dotrun/configs/01-paths.config
# PATH Configuration - MUST LOAD FIRST
# Last Updated: 2024-01-15

# Homebrew (Apple Silicon M1/M2/M3)
export PATH="/opt/homebrew/bin:$PATH"

# ❌ BAD: No context
export PATH="/opt/homebrew/bin:$PATH"
```

### 9. File Permissions

```bash
# Lock down sensitive files
chmod 600 ~/.config/dotrun/configs/05-api.config
chmod 600 ~/.config/dotrun/configs/90-local.config

# Verify
ls -la ~/.config/dotrun/configs/*.config
```

### 10. Version Control Strategy

```bash
# Track non-secret configs
git add ~/.config/dotrun/configs/01-paths.config
git add ~/.config/dotrun/configs/02-xdg.config
git add ~/.config/dotrun/configs/10-development.config
git add ~/.config/dotrun/configs/20-cloud.config

# Never track secrets
echo "configs/05-api.config" >>.gitignore
echo "configs/90-local.config" >>.gitignore
echo "configs/*local.config" >>.gitignore
echo "configs/*secrets.config" >>.gitignore
```

## Troubleshooting

### Files Aren't Loading

**Symptom**: Environment variables not set after opening new terminal.

**Diagnosis**:

```bash
# Check if ~/.drrc exists
ls -la ~/.drrc

# Check if shell sources it
grep -i "drrc" ~/.bashrc ~/.zshrc

# List config files
ls -1 ~/.config/dotrun/configs/*.config
```

**Fix**:

```bash
# Ensure ~/.drrc is sourced in shell RC
echo '[ -f "$HOME/.drrc" ] && . "$HOME/.drrc"' >>~/.bashrc
# or for zsh:
echo '[ -f "$HOME/.drrc" ] && . "$HOME/.drrc"' >>~/.zshrc

# Reload shell
exec $SHELL
```

### Wrong Load Order

**Symptom**: Variables undefined or PATH wrong despite being in configs.

**Diagnosis**:

```bash
# Check load order
ls -1 ~/.config/dotrun/configs

# Should be: 01-paths.config, 02-xdg.config, etc.
# NOT: 1-paths.config, 10-development.config, 2-xdg.config
```

**Fix**:

```bash
# Rename to use two-digit prefixes
mv ~/.config/dotrun/configs/1-paths.config \
  ~/.config/dotrun/configs/01-paths.config

mv ~/.config/dotrun/configs/2-xdg.config \
  ~/.config/dotrun/configs/02-xdg.config

# Reload
source ~/.drrc
```

### PATH Not Correct

**Symptom**: Commands not found or wrong versions executing.

**Diagnosis**:

```bash
# View PATH line-by-line
printf "%s\n" "${PATH//:/$'\n'}"

# Check if 01-paths.config exists
cat ~/.config/dotrun/configs/01-paths.config

# Look for PATH resets (PATH= without $PATH)
grep -n "^export PATH=" ~/.config/dotrun/configs/*.config
```

**Fix**:

```bash
# Ensure PATH set in 01-paths.config
vim ~/.config/dotrun/configs/01-paths.config

# Use this pattern (prepend):
export PATH="$HOME/.local/bin:$PATH"

# NOT this (reset):
export PATH="$HOME/.local/bin" # Wrong! Loses system paths

# Reload
source ~/.drrc
```

### Variables Not Set

**Symptom**: `echo "$VAR"` shows empty despite being in config file.

**Diagnosis**:

```bash
# Check syntax
bash -n ~/.config/dotrun/configs/10-development.config

# Look for the export
grep "EDITOR" ~/.config/dotrun/configs/*.config

# Check if file is being loaded
ls ~/.config/dotrun/configs/*.config
```

**Fix**:

```bash
# Ensure correct export syntax
# ✅ GOOD
export EDITOR="vim"

# ❌ BAD (missing export)
EDITOR="vim"

# ❌ BAD (missing quotes)
export EDITOR=vim with flags

# Reload
source ~/.drrc
```

### Secrets Missing

**Symptom**: API calls fail with authentication errors.

**Diagnosis**:

```bash
# Check if secrets file exists
ls -la ~/.config/dotrun/configs/05-api.config

# Check permissions
ls -la ~/.config/dotrun/configs/05-api.config
# Should show: -rw------- (600)

# Check if variable set (safely)
[ -n "$GITHUB_TOKEN" ] && echo "Set" || echo "Not set"
```

**Fix**:

```bash
# Create if missing
touch ~/.config/dotrun/configs/05-api.config
chmod 600 ~/.config/dotrun/configs/05-api.config

# Add export statements
export GITHUB_TOKEN="ghp_xxxxx"

# Reload
source ~/.drrc
```

### Syntax Errors

**Symptom**: Error messages when opening terminal or sourcing configs.

**Diagnosis**:

```bash
# Test each file individually
bash -n ~/.config/dotrun/configs/01-paths.config
bash -n ~/.config/dotrun/configs/10-development.config

# Look for common issues
grep -n "export" ~/.config/dotrun/configs/*.config
```

**Common Issues**:

```bash
# ❌ Unmatched quotes
export VAR="value with "quotes" inside"
# Fix: Escape inner quotes
export VAR="value with \"quotes\" inside"

# ❌ Missing closing quote
export VAR="value
# Fix: Close quote on same line
export VAR="value"

# ❌ Spaces around =
export VAR = "value"
# Fix: No spaces
export VAR="value"
```

### Shell-Specific Issues

**Bash vs Zsh**:

```bash
# Export syntax is the same
export VAR="value" # Works in both

# But sourcing differs slightly
# Bash: source or .
source ~/.drrc
. ~/.drrc

# Zsh: source or .
source ~/.drrc
. ~/.drrc

# Both work with both shells for basic configs
```

### Duplicate Entries

**Symptom**: PATH contains same directory multiple times.

**Diagnosis**:

```bash
# Check for duplicates
printf "%s\n" "${PATH//:/$'\n'}" | sort | uniq -c | grep -v "^ *1 "
```

**Fix**:

```bash
# Use conditional PATH additions (advanced)
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
  export PATH="$HOME/.local/bin:$PATH"
fi

# Or: Prefer new shell over re-sourcing
exec $SHELL # Instead of: source ~/.drrc
```

### Quick Verification Commands

```bash
# Show load order
ls -1 ~/.config/dotrun/configs

# Show PATH line-by-line
printf "%s\n" "${PATH//:/$'\n'}"

# Check for conflicts
grep -R "export EDITOR" ~/.config/dotrun/configs

# Reload configs
source ~/.drrc

# Test in fresh shell
exec $SHELL

# Validate syntax
for f in ~/.config/dotrun/configs/*.config; do
  echo "Checking: $f"
  bash -n "$f" || echo "Syntax error in $f"
done
```

## Next Steps

With configuration management set up:

1. **Manage Aliases**: Set up [Alias Management](Alias-Management.md) using similar NN-category pattern
2. **Secure Secrets**: Review [Security Best Practices](#security-considerations) for secrets management
3. **Script Development**: Use configs in [Script Development](Script-Development.md)
4. **Collections**: Share configs via [Collections](Collections.md)
5. **Team Setup**: Coordinate [Team Workflows](Team-Workflows.md) with shared configs

---

[← Developer Experience](Developer-Experience.md) | [Alias Management →](Alias-Management.md) | [Top ↑](#configuration-management)